api

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