Many of the API calls in the admin api will require an access_token for a
-server admin. (Note that a server admin is distinct from a room admin.)
-
A user can be marked as a server admin by updating the database directly, e.g.:
-
UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
-
-
A new server admin user can also be created using the register_new_matrix_user
-command. This is a script that is located in the scripts/ directory, or possibly
-already on your $PATH depending on how Synapse was installed.
-
Finding your user's access_token is client-dependent, but will usually be shown in the client's settings.
Once you have your access_token, you will need to authenticate each request to an Admin API endpoint by
-providing the token as either a query parameter or a request header. To add it as a request header in cURL:
This API allows you to manage tokens which can be used to authenticate
-registration requests, as proposed in
-MSC3231.
-To use it, you will need to enable the registration_requires_token config
-option, and authenticate by providing an access_token for a server admin:
-see Admin API.
-Note that this API is still experimental; not all clients may support it yet.
Most endpoints make use of JSON objects that contain details about tokens.
-These objects have the following fields:
-
-
token: The token which can be used to authenticate registration.
-
uses_allowed: The number of times the token can be used to complete a
-registration before it becomes invalid.
-
pending: The number of pending uses the token has. When someone uses
-the token to authenticate themselves, the pending counter is incremented
-so that the token is not used more than the permitted number of times.
-When the person completes registration the pending counter is decremented,
-and the completed counter is incremented.
-
completed: The number of times the token has been used to successfully
-complete a registration.
-
expiry_time: The latest time the token is valid. Given as the number of
-milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
-To convert this into a human-readable form you can remove the milliseconds
-and use the date command. For example, date -d '@1625394937'.
Lists all tokens and details about them. If the request is successful, the top
-level JSON object will have a registration_tokens key which is an array of
-registration token objects.
-
GET /_synapse/admin/v1/registration_tokens
-
-
Optional query parameters:
-
-
valid: true or false. If true, only valid tokens are returned.
-If false, only tokens that have expired or have had all uses exhausted are
-returned. If omitted, all tokens are returned regardless of validity.
Create a new registration token. If the request is successful, the newly created
-token will be returned as a registration token object in the response body.
-
POST /_synapse/admin/v1/registration_tokens/new
-
-
The request body must be a JSON object and can contain the following fields:
-
-
token: The registration token. A string of no more than 64 characters that
-consists only of characters matched by the regex [A-Za-z0-9-_].
-Default: randomly generated.
-
uses_allowed: The integer number of times the token can be used to complete
-a registration before it becomes invalid.
-Default: null (unlimited uses).
-
expiry_time: The latest time the token is valid. Given as the number of
-milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
-You could use, for example, date '+%s000' -d 'tomorrow'.
-Default: null (token does not expire).
-
length: The length of the token randomly generated if token is not
-specified. Must be between 1 and 64 inclusive. Default: 16.
-
-
If a field is omitted the default is used.
-
Example using defaults:
-
POST /_synapse/admin/v1/registration_tokens/new
-
-{}
-
Update the number of allowed uses or expiry time of a token. If the request is
-successful, the updated token will be returned as a registration token object
-in the response body.
-
PUT /_synapse/admin/v1/registration_tokens/<token>
-
-
Path parameters:
-
-
token: The registration token to update.
-
-
The request body must be a JSON object and can contain the following fields:
-
-
uses_allowed: The integer number of times the token can be used to complete
-a registration before it becomes invalid. By setting uses_allowed to 0
-the token can be easily made invalid without deleting it.
-If null the token will have an unlimited number of uses.
-
expiry_time: The latest time the token is valid. Given as the number of
-milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch).
-If null the token will not expire.
-
-
If a field is omitted its value is not modified.
-
Example:
-
PUT /_synapse/admin/v1/registration_tokens/defg
-
-{
- "expiry_time": 4781243146000 // 2121-07-06 11:05:46 UTC
-}
-
Logger name (synapse.access.(http\|https).<tag>, where 'tag' is defined in the listeners config section, normally the port)
-
CCCC
Line number in code
-
DDDD
Log Level
-
EEEE
Request Identifier (This identifier is shared by related log lines)
-
FFFF
Source IP (Or X-Forwarded-For if enabled)
-
GGGG
Server Port
-
HHHH
Federated Server or Local User making request (blank if unauthenticated or not supplied)
-
IIII
Total Time to process the request
-
JJJJ
Time to send response over network once generated (this may be negative if the socket is closed before the response is generated)
-
KKKK
Userland CPU time
-
LLLL
System CPU time
-
MMMM
Total time waiting for a free DB connection from the pool across all parallel DB work from this request
-
NNNN
Total time waiting for response to DB queries across all parallel DB work from this request
-
OOOO
Count of DB transactions performed
-
PPPP
Response body size
-
QQQQ
Response status code (prefixed with ! if the socket was closed before the response was generated)
-
RRRR
Request
-
SSSS
User-agent
-
TTTT
Events fetched from DB to service this request (note that this does not include events fetched from the cache)
-
-
MMMM / NNNN can be greater than IIII if there are multiple slow database queries
-running in parallel.
-
Some actions can result in multiple identical http requests, which will return
-the same data, but only the first request will report time/transactions in
-KKKK/LLLL/MMMM/NNNN/OOOO - the others will be awaiting the first query to return a
-response and will simultaneously return with the first request, but with very
-small processing times.