+ +

Federation API

This API allows a server administrator to manage Synapse's federation with other homeservers.

Note: This API is new, experimental and "subject to change".

List of destinations

This API gets the current destination retry timing info for all remote servers.

The list contains all the servers with which the server federates, +regardless of whether an error occurred or not. +If an error occurs, it may take up to 20 minutes for the error to be displayed here, +as a complete retry must have failed.

The API is:

A standard request with no filtering:

GET /_synapse/admin/v1/federation/destinations
+

A response body like the following is returned:

{
+   "destinations":[
+      {
+         "destination": "matrix.org",
+         "retry_last_ts": 1557332397936,
+         "retry_interval": 3000000,
+         "failure_ts": 1557329397936,
+         "last_successful_stream_ordering": null
+      }
+   ],
+   "total": 1
+}
+

To paginate, check for next_token and if present, call the endpoint again +with from set to the value of next_token. This will return a new page.

If the endpoint does not return a next_token then there are no more destinations +to paginate through.

Parameters

The following query parameters are available:

from - Offset in the returned list. Defaults to 0.
limit - Maximum amount of destinations to return. Defaults to 100.
order_by - The method in which to sort the returned list of destinations. +Valid values are: +
- destination - Destinations are ordered alphabetically by remote server name. +This is the default.
- retry_last_ts - Destinations are ordered by time of last retry attempt in ms.
- retry_interval - Destinations are ordered by how long until next retry in ms.
- failure_ts - Destinations are ordered by when the server started failing in ms.
- last_successful_stream_ordering - Destinations are ordered by the stream ordering +of the most recent successfully-sent PDU.
+
dir - Direction of room order. Either f for forwards or b for backwards. Setting +this value to b will reverse the above sort order. Defaults to f.

Caution: The database only has an index on the column destination. +This means that if a different sort order is used, +this can cause a large load on the database, especially for large environments.

Response

The following fields are returned in the JSON response body:

destinations - An array of objects, each containing information about a destination. +Destination objects contain the following fields: +
- destination - string - Name of the remote server to federate.
- retry_last_ts - integer - The last time Synapse tried and failed to reach the +remote server, in ms. This is 0 if the last attempt to communicate with the +remote server was successful.
- retry_interval - integer - How long since the last time Synapse tried to reach +the remote server before trying again, in ms. This is 0 if no further retrying occuring.
- failure_ts - nullable integer - The first time Synapse tried and failed to reach the +remote server, in ms. This is null if communication with the remote server has never failed.
- last_successful_stream_ordering - nullable integer - The stream ordering of the most +recent successfully-sent PDU +to this destination, or null if this information has not been tracked yet.
+
next_token: string representing a positive integer - Indication for pagination. See above.
total - integer - Total number of destinations.

Destination Details API

This API gets the retry timing info for a specific remote server.

The API is:

GET /_synapse/admin/v1/federation/destinations/<destination>
+

A response body like the following is returned:

{
+   "destination": "matrix.org",
+   "retry_last_ts": 1557332397936,
+   "retry_interval": 3000000,
+   "failure_ts": 1557329397936,
+   "last_successful_stream_ordering": null
+}
+

Parameters

The following parameters should be set in the URL:

destination - Name of the remote server.

Response

The response fields are the same like in the destinations array in +List of destinations response.

Destination rooms

This API gets the rooms that federate with a specific remote server.

The API is:

GET /_synapse/admin/v1/federation/destinations/<destination>/rooms
+

A response body like the following is returned:

{
+   "rooms":[
+      {
+         "room_id": "!OGEhHVWSdvArJzumhm:matrix.org",
+         "stream_ordering": 8326
+      },
+      {
+         "room_id": "!xYvNcQPhnkrdUmYczI:matrix.org",
+         "stream_ordering": 93534
+      }
+   ],
+   "total": 2
+}
+

To paginate, check for next_token and if present, call the endpoint again +with from set to the value of next_token. This will return a new page.

If the endpoint does not return a next_token then there are no more destinations +to paginate through.

Parameters

The following parameters should be set in the URL:

destination - Name of the remote server.

The following query parameters are available:

from - Offset in the returned list. Defaults to 0.
limit - Maximum amount of destinations to return. Defaults to 100.
dir - Direction of room order by room_id. Either f for forwards or b for +backwards. Defaults to f.

Response

The following fields are returned in the JSON response body:

rooms - An array of objects, each containing information about a room. +Room objects contain the following fields: +
- room_id - string - The ID of the room.
- stream_ordering - integer - The stream ordering of the most recent +successfully-sent PDU +to this destination in this room.
+
next_token: string representing a positive integer - Indication for pagination. See above.
total - integer - Total number of destinations.

Reset connection timeout

Synapse makes federation requests to other homeservers. If a federation request fails, +Synapse will mark the destination homeserver as offline, preventing any future requests +to that server for a "cooldown" period. This period grows over time if the server +continues to fail its responses +(exponential backoff).

Admins can cancel the cooldown period with this API.

This API resets the retry timing for a specific remote server and tries to connect to +the remote server again. It does not wait for the next retry_interval. +The connection must have previously run into an error and retry_last_ts +(Destination Details API) must not be equal to 0.

The connection attempt is carried out in the background and can take a while +even if the API already returns the http status 200.

The API is:

POST /_synapse/admin/v1/federation/destinations/<destination>/reset_connection
+
+{}
+

Parameters

The following parameters should be set in the URL:

destination - Name of the remote server.

+ +

Registration Tokens

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.

Registration token objects

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'.

List all tokens

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.

Example:

GET /_synapse/admin/v1/registration_tokens
+

200 OK
+
+{
+    "registration_tokens": [
+        {
+            "token": "abcd",
+            "uses_allowed": 3,
+            "pending": 0,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "pqrs",
+            "uses_allowed": 2,
+            "pending": 1,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "wxyz",
+            "uses_allowed": null,
+            "pending": 0,
+            "completed": 9,
+            "expiry_time": 1625394937000    // 2021-07-04 10:35:37 UTC
+        }
+    ]
+}
+

Example using the valid query parameter:

GET /_synapse/admin/v1/registration_tokens?valid=false
+

200 OK
+
+{
+    "registration_tokens": [
+        {
+            "token": "pqrs",
+            "uses_allowed": 2,
+            "pending": 1,
+            "completed": 1,
+            "expiry_time": null
+        },
+        {
+            "token": "wxyz",
+            "uses_allowed": null,
+            "pending": 0,
+            "completed": 9,
+            "expiry_time": 1625394937000    // 2021-07-04 10:35:37 UTC
+        }
+    ]
+}
+

Get one token

Get details about a single token. If the request is successful, the response +body will be a registration token object.

GET /_synapse/admin/v1/registration_tokens/<token>
+

Path parameters:

token: The registration token to return details of.

Example:

GET /_synapse/admin/v1/registration_tokens/abcd
+

200 OK
+
+{
+    "token": "abcd",
+    "uses_allowed": 3,
+    "pending": 0,
+    "completed": 1,
+    "expiry_time": null
+}
+

Create token

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
+
+{}
+

200 OK
+
+{
+    "token": "0M-9jbkf2t_Tgiw1",
+    "uses_allowed": null,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": null
+}
+

Example specifying some fields:

POST /_synapse/admin/v1/registration_tokens/new
+
+{
+    "token": "defg",
+    "uses_allowed": 1
+}
+

200 OK
+
+{
+    "token": "defg",
+    "uses_allowed": 1,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": null
+}
+

Update token

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
+}
+

200 OK
+
+{
+    "token": "defg",
+    "uses_allowed": 1,
+    "pending": 0,
+    "completed": 0,
+    "expiry_time": 4781243146000
+}
+

Delete token

Delete a registration token. If the request is successful, the response body +will be an empty JSON object.

DELETE /_synapse/admin/v1/registration_tokens/<token>
+

Path parameters:

token: The registration token to delete.

Example:

DELETE /_synapse/admin/v1/registration_tokens/wxyz
+

200 OK
+
+{}
+

Errors

If a request fails a "standard error response" will be returned as defined in +the Matrix Client-Server API specification.

For example, if the token specified in a path parameter does not exist a +404 Not Found error will be returned.

GET /_synapse/admin/v1/registration_tokens/1234
+

404 Not Found
+
+{
+    "errcode": "M_NOT_FOUND",
+    "error": "No such registration token: 1234"
+}
+

+ +

Part	Explanation
AAAA	Timestamp request was logged (not recieved)
BBBB	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)