Skip to content

api

Jump to bottom
xelantro edited this page Aug 27, 2021 · 18 revisions
Clone this wiki locally

curl

administrator

following actions are only available if admin_api_shared_secret is set in the config and you have access to this value. this value has to be different from the default APIAdminPassword used in the examples here, otherwise these endpoints are disabled.

to make the admin api accessible via the web refer to reverse-proxy

creating a new token

curl -X POST \
     -H "Authorization: SharedSecret <APIAdminPassword>" \
     -H "Content-Type: application/json" \
     -d '{"max_usage": 1, "expiration_date": "2021-12-04"}' \
     http://localhost:5000/api/token

or

example response:
{
  "active": true,
  "disabled": false,
  "expiration_date": "2021-12-04 00:00:00",
  "ips": [],
  "max_usage": 1,
  "name": "DoubleWizardSki",
  "used": 0
}

or

{"errcode":"MR_BAD_SECRET", "error":"wrong shared secret"}

or

{"errcode":"MR_BAD_DATE_FORMAT", "error":"date wasn't in YYYY-MM-DD format"}

listing all tokens

curl -H "Authorization: SharedSecret <APIAdminPassword>" \
     http://localhost:5000/api/token
example response:
[{"active":true,"disabled":false,"expiration_date":"2021-12-04 00:00:00","ips":[],"max_usage":1,"name":"DoubleWizardSki","used":0}]

disabling/modifying a token

the following values can't be modified: ips, active and name

curl -X PATCH \
     -H "Authorization: SharedSecret <APIAdminPassword>" \
     -H "Content-Type: application/json" \
     -d '{"disabled": true}' \
     http://localhost:5000/api/token/DoubleWizardSki
example response:
{
  "active": true,
  "disabled": true,
  "expiration_date": "2021-12-04 00:00:00",
  "ips": [],
  "max_usage": 1,
  "name": "DoubleWizardSki",
  "used": 0
}

or

{"errcode":"MR_BAD_USER_REQUEST", "error":"you're not allowed to change this property"}

getting the status of a token

curl -H "Authorization: SharedSecret <APIAdminPassword>" \
     http://localhost:5000/api/token/DoubleWizardSki
example response:
{
  "active": true,
  "disabled": true,
  "expiration_date": "2021-12-04 00:00:00",
  "ips": [],
  "max_usage": 1,
  "name": "DoubleWizardSki",
  "used": 0
}
{"errcode":"MR_TOKEN_NOT_FOUND", "error":"token does not exist"}

getting the current version of matrix-registration

curl -H "Authorization: SharedSecret <APIAdminPassword>" \
     http://localhost:5000/api/version
example response:
{"version":"0.9.0"}

user

these actions are available to every user

registering an account

curl -X POST \
     -F 'username=test' \
     -F 'password=verysecure' \
     -F 'confirm=verysecure' \
     -F 'token=DoubleWizardSki' \
     http://localhost:5000/register