+ +

Registration Tokens

Note: This API is disabled when MSC3861 is enabled. See #15582

This API allows you to manage tokens which can be used to authenticate +registration requests, as proposed in +MSC3231 +and stabilised in version 1.2 of the Matrix specification. +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.

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

+ +

Admin FAQ

How do I become a server admin?

If your server already has an admin account you should use the +User Admin API +to promote other accounts to become admins.

If you don't have any admin accounts yet you won't be able to use the admin API, +so you'll have to edit the database manually. Manually editing the database is +generally not recommended so once you have an admin account: use the admin APIs +to make further changes.

UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
+

What servers are my server talking to?

Run this sql query on your db:

SELECT * FROM destinations;
+

What servers are currently participating in this room?

Run this sql query on your db:

SELECT DISTINCT split_part(state_key, ':', 2)
+FROM current_state_events
+WHERE room_id = '!cURbafjkfsMDVwdRDQ:matrix.org' AND membership = 'join';
+

What users are registered on my server?

SELECT NAME from users;
+

How can I export user data?

Synapse includes a Python command to export data for a specific user. It takes the homeserver +configuration file and the full Matrix ID of the user to export:

python -m synapse.app.admin_cmd -c <config_file> export-data <user_id> --output-directory <directory_path>
+

If you uses Poetry +to run Synapse:

poetry run python -m synapse.app.admin_cmd -c <config_file> export-data <user_id> --output-directory <directory_path>
+

The directory to store the export data in can be customised with the +--output-directory parameter; ensure that the provided directory is +empty. If this parameter is not provided, Synapse defaults to creating +a temporary directory (which starts with "synapse-exfiltrate") in /tmp, +/var/tmp, or /usr/tmp, in that order.

The exported data has the following layout:

output-directory
+├───rooms
+│   └───<room_id>
+│       ├───events
+│       ├───state
+│       ├───invite_state
+│       └───knock_state
+├───user_data
+│   ├───account_data
+│   │   ├───global
+│   │   └───<room_id>
+│   ├───connections
+│   ├───devices
+│   └───profile
+└───media_ids
+    └───<media_id>
+

The media_ids folder contains only the metadata of the media uploaded by the user. +It does not contain the media itself. +Furthermore, only the media_ids that Synapse manages itself are exported. +If another media repository (e.g. matrix-media-repo) +is used, the data must be exported separately.

With the media_ids the media files can be downloaded. +Media that have been sent in encrypted rooms are only retrieved in encrypted form. +The following script can help with download the media files:

#!/usr/bin/env bash
+
+# Parameters
+#
+#   source_directory: Directory which contains the export with the media_ids.
+#   target_directory: Directory into which all files are to be downloaded.
+#   repository_url: Address of the media repository resp. media worker.
+#   serverName: Name of the server (`server_name` from homeserver.yaml).
+#
+#   Example:
+#       ./download_media.sh /tmp/export_data/media_ids/ /tmp/export_data/media_files/ http://localhost:8008 matrix.example.com
+
+source_directory=$1
+target_directory=$2
+repository_url=$3
+serverName=$4
+
+mkdir -p $target_directory
+
+for file in $source_directory/*; do
+    filename=$(basename ${file})
+    url=$repository_url/_matrix/media/v3/download/$serverName/$filename
+    echo "Downloading $filename - $url"
+    if ! wget -o /dev/null -P $target_directory $url; then
+        echo "Could not download $filename"
+    fi
+done
+

How do I upgrade from a very old version of Synapse to the latest?

See this section in the +upgrade docs.

Manually resetting passwords

Users can reset their password through their client. Alternatively, a server admin +can reset a user's password using the admin API.

I have a problem with my server. Can I just delete my database and start again?

Deleting your database is unlikely to make anything better.

It's easy to make the mistake of thinking that you can start again from a clean +slate by dropping your database, but things don't work like that in a federated +network: lots of other servers have information about your server.

For example: other servers might think that you are in a room, your server will +think that you are not, and you'll probably be unable to interact with that room +in a sensible way ever again.

In general, there are better solutions to any problem than dropping the database. +Come and seek help in https://matrix.to/#/#synapse:matrix.org.

There are two exceptions when it might be sensible to delete your database and start again:

You have never joined any rooms which are federated with other servers. For +instance, a local deployment which the outside world can't talk to.
You are changing the server_name in the homeserver configuration. In effect +this makes your server a completely new one from the point of view of the network, +so in this case it makes sense to start with a clean database. +(In both cases you probably also want to clear out the media_store.)

I've stuffed up access to my room, how can I delete it to free up the alias?

Using the following curl command:

curl -H 'Authorization: Bearer <access-token>' -X DELETE https://matrix.org/_matrix/client/r0/directory/room/<room-alias>
+

<access-token> - can be obtained in riot by looking in the riot settings, down the bottom is: +Access Token:<click to reveal>

<room-alias> - the room alias, eg. #my_room:matrix.org this possibly needs to be URL encoded also, for example %23my_room%3Amatrix.org

How can I find the lines corresponding to a given HTTP request in my homeserver log?

Synapse tags each log line according to the HTTP request it is processing. When +it finishes processing each request, it logs a line containing the words +Processed request: . For example:

2019-02-14 22:35:08,196 - synapse.access.http.8008 - 302 - INFO - GET-37 - ::1 - 8008 - {@richvdh:localhost} Processed request: 0.173sec/0.001sec (0.002sec, 0.000sec) (0.027sec/0.026sec/2) 687B 200 "GET /_matrix/client/r0/sync HTTP/1.1" "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36" [0 dbevts]"
+

Here we can see that the request has been tagged with GET-37. (The tag depends +on the method of the HTTP request, so might start with GET-, PUT-, POST-, +OPTIONS- or DELETE-.) So to find all lines corresponding to this request, we can do:

grep 'GET-37' homeserver.log
+

If you want to paste that output into a github issue or matrix room, please +remember to surround it with triple-backticks (```) to make it legible +(see quoting code).

What do all those fields in the 'Processed' line mean?

See Request log format.

What are the biggest rooms on my server?

SELECT s.canonical_alias, g.room_id, count(*) AS num_rows
+FROM
+  state_groups_state AS g,
+  room_stats_state AS s
+WHERE g.room_id = s.room_id
+GROUP BY s.canonical_alias, g.room_id
+ORDER BY num_rows desc
+LIMIT 10;
+

You can also use the List Room API +and order_by state_events.

People can't accept room invitations from me

The typical failure mode here is that you send an invitation to someone +to join a room or direct chat, but when they go to accept it, they get an +error (typically along the lines of "Invalid signature"). They might see +something like the following in their logs:

2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
+

This is normally caused by a misconfiguration in your reverse-proxy. See the reverse proxy docs and double-check that your settings are correct.

Help!! Synapse is slow and eats all my RAM/CPU!

First, ensure you are running the latest version of Synapse, using Python 3 +with a PostgreSQL database.

Synapse's architecture is quite RAM hungry currently - we deliberately +cache a lot of recent room data and metadata in RAM in order to speed up +common requests. We'll improve this in the future, but for now the easiest +way to either reduce the RAM usage (at the risk of slowing things down) +is to set the almost-undocumented SYNAPSE_CACHE_FACTOR environment +variable. The default is 0.5, which can be decreased to reduce RAM usage +in memory constrained environments, or increased if performance starts to +degrade.

However, degraded performance due to a low cache factor, common on +machines with slow disks, often leads to explosions in memory use due +backlogged requests. In this case, reducing the cache factor will make +things worse. Instead, try increasing it drastically. 2.0 is a good +starting value.

Using libjemalloc can also yield a significant +improvement in overall memory use, and especially in terms of giving back +RAM to the OS. To use it, the library must simply be put in the +LD_PRELOAD environment variable when launching Synapse. On Debian, this +can be done by installing the libjemalloc1 package and adding this +line to /etc/default/matrix-synapse:

LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
+

This made a significant difference on Python 2.7 - it's unclear how +much of an improvement it provides on Python 3.x.

If you're encountering high CPU use by the Synapse process itself, you +may be affected by a bug with presence tracking that leads to a +massive excess of outgoing federation requests (see discussion). If metrics +indicate that your server is also issuing far more outgoing federation +requests than can be accounted for by your users' activity, this is a +likely cause. The misbehavior can be worked around by disabling presence +in the Synapse config file: see here.

Running out of File Handles

If Synapse runs out of file handles, it typically fails badly - live-locking +at 100% CPU, and/or failing to accept new TCP connections (blocking the +connecting client). Matrix currently can legitimately use a lot of file handles, +thanks to busy rooms like #matrix:matrix.org containing hundreds of participating +servers. The first time a server talks in a room it will try to connect +simultaneously to all participating servers, which could exhaust the available +file descriptors between DNS queries & HTTPS sockets, especially if DNS is slow +to respond. (We need to improve the routing algorithm used to be better than +full mesh, but as of March 2019 this hasn't happened yet).

If you hit this failure mode, we recommend increasing the maximum number of +open file handles to be at least 4096 (assuming a default of 1024 or 256). +This is typically done by editing /etc/security/limits.conf

Separately, Synapse may leak file handles if inbound HTTP requests get stuck +during processing - e.g. blocked behind a lock or talking to a remote server etc. +This is best diagnosed by matching up the 'Received request' and 'Processed request' +log lines and looking for any 'Processed request' lines which take more than +a few seconds to execute. Please let us know at #synapse:matrix.org if +you see this failure mode so we can help debug it, however.

+ +

Statistic Name	Type	Description
`homeserver`	string	The homeserver's server name.
`memory_rss`	int	The memory usage of the process (in kilobytes on Unix-based systems, bytes on MacOS).
`cpu_average`	int	CPU time in % of a single core (not % of all cores).
`server_context`	string	An arbitrary string used to group statistics from a set of homeservers.
`timestamp`	int	The current time, represented as the number of seconds since the epoch.
`uptime_seconds`	int	The number of seconds since the homeserver was last started.
`python_version`	string	The Python version number in use (e.g "3.7.1"). Taken from `sys.version_info`.
`total_users`	int	The number of registered users on the homeserver.
`total_nonbridged_users`	int	The number of users, excluding those created by an Application Service.
`daily_user_type_native`	int	The number of native users created in the last 24 hours.
`daily_user_type_guest`	int	The number of guest users created in the last 24 hours.
`daily_user_type_bridged`	int	The number of users created by Application Services in the last 24 hours.
`total_room_count`	int	The total number of rooms present on the homeserver.
`daily_active_users`	int	The number of unique users¹ that have used the homeserver in the last 24 hours.
`monthly_active_users`	int	The number of unique users¹ that have used the homeserver in the last 30 days.
`daily_active_rooms`	int	The number of rooms that have had a (state) event with the type `m.room.message` sent in them in the last 24 hours.
`daily_active_e2ee_rooms`	int	The number of rooms that have had a (state) event with the type `m.room.encrypted` sent in them in the last 24 hours.
`daily_messages`	int	The number of (state) events with the type `m.room.message` seen in the last 24 hours.
`daily_e2ee_messages`	int	The number of (state) events with the type `m.room.encrypted` seen in the last 24 hours.
`daily_sent_messages`	int	The number of (state) events sent by a local user with the type `m.room.message` seen in the last 24 hours.
`daily_sent_e2ee_messages`	int	The number of (state) events sent by a local user with the type `m.room.encrypted` seen in the last 24 hours.
`r30v2_users_all`	int	The number of 30 day retained users, with a revised algorithm. Defined as users that appear more than once in the past 60 days, and have more than 30 days between the most and least recent appearances in the past 60 days. Includes clients that do not fit into the below r30 client types.
`r30v2_users_android`	int	The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "android" (case-insensitive) in the user agent string.
`r30v2_users_ios`	int	The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "ios" (case-insensitive) in the user agent string.
`r30v2_users_electron`	int	The number of 30 day retained users, as defined above. Filtered only to clients with ("riot" or "element") and "electron" (case-insensitive) in the user agent string.
`r30v2_users_web`	int	The number of 30 day retained users, as defined above. Filtered only to clients with "mozilla" or "gecko" (case-insensitive) in the user agent string.
`cache_factor`	int	The configured `global factor` value for caching.
`event_cache_size`	int	The configured `event_cache_size` value for caching.
`database_engine`	string	The database engine that is in use. Either "psycopg2" meaning PostgreSQL is in use, or "sqlite3" for SQLite3.
`database_server_version`	string	The version of the database server. Examples being "10.10" for PostgreSQL server version 10.0, and "3.38.5" for SQLite 3.38.5 installed on the system.
`log_level`	string	The log level in use. Examples are "INFO", "WARNING", "ERROR", "DEBUG", etc.

Part	Explanation
AAAA	Timestamp request was logged (not received)
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). If this is of the form `@aaa:example.com
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 Suffixed with `!` if the socket was closed before the response was generated. A `499!` status code indicates that Synapse also cancelled request processing after the socket was closed.
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)