How to Restrict User Registration on a Self-Hosted Matrix Server

On a self-hosted Matrix server, “restrict registration” can mean anything from stopping all public sign-ups to allowing only people who have an invitation code. For Synapse, the simplest choice is to disable public registration. If you still want new people to join, require registration tokens and give each person a limited, expiring token. These controls affect creation of new local accounts; they do not remove existing users or disable Matrix federation.

Choose the control that fits your server

The examples below are for Synapse. Dendrite, Conduit, and other homeserver implementations use different configuration and administration interfaces. Check your server’s own documentation before applying Synapse settings.

Option 1: Turn off public registration

For a private home server, a small organization, or a server where an administrator provisions each account, disable client registration in the active Synapse configuration:

enable_registration: false

Synapse documents this setting as disabled by default. Edit the configuration file that your service or container actually loads, validate the YAML, then restart Synapse using your normal service-management process. A Docker deployment may mount the configuration from a host path, so editing a similarly named file inside the container may not change the file used at startup.

With registration off, users cannot create new accounts through the ordinary client registration flow. Administrators can still create accounts through supported administrative methods. Synapse specifically warns that setting registration_shared_secret permits account creation using that secret even while enable_registration is false. Treat it as a high-impact credential: keep it out of repositories, chat, and public environment dumps; limit access; and retain it only if your admin workflow needs it. Anyone with the secret can create accounts, including administrator accounts.

If you use OIDC, CAS, or another SSO integration, check that provider’s own automatic-registration setting too. Synapse documents provider-level registration switches because a user may otherwise be created automatically on first successful SSO login. For OIDC, review oidc_providers[].enable_registration as well as the general registration setting.

Option 2: Allow registration only with tokens

Use registration tokens when members should be able to create their own accounts, but sign-ups should be approved or distributed by an administrator. In the Synapse configuration, set both values:

enable_registration: true
registration_requires_token: true

Both are needed: the token setting requires a token during registration, while registration itself must also be enabled. Apply the change and restart Synapse. Existing accounts and previously created tokens are not removed by changing this setting.

Create a limited-use token

Synapse provides a registration-token Admin API. Requests require an administrator access token. For example, this request creates a token that can complete one registration:

curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/registration_tokens/new" \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"uses_allowed": 1}'

Replace the environment variables with your homeserver base URL and an admin access token. Keep the admin token private and avoid pasting commands containing real credentials into shared logs or support posts. The API can also accept an expiry time in milliseconds since the Unix epoch. Use a one-use token for an individual invite and set an expiry when your workflow can calculate and maintain it reliably. A token with omitted limits may have unlimited uses and no expiry, so review the returned fields before distributing it.

To inspect tokens, an administrator can call GET /_synapse/admin/v1/registration_tokens. The response includes allowed uses, pending registrations, completed registrations, and expiry. If a token is leaked, update its allowed uses to zero or delete it through the documented Admin API. A token is a sign-up credential, not a Matrix room invitation; it does not automatically join the new account to a room.

Important compatibility note: Synapse’s registration-token Admin API is disabled when Matrix Authentication Service (MAS) integration is enabled. In that setup, use the MAS Admin API or MAS CLI documented for your deployment instead. Do not assume a Synapse token command will work unchanged with MAS.

Option 3: Add checks to public registration

If your goal is to let anyone request an account, requiring tokens may be too restrictive. Synapse’s configuration also documents CAPTCHA and third-party identifier requirements as possible checks. CAPTCHA depends on a correctly configured provider and may add accessibility and privacy costs. Requiring an email address or phone number can add setup and verification dependencies; it is not the same as approving each account. Confirm which verification services your version and client flow actually support before making a 3PID requirement a gate.

Rate limiting is useful alongside these controls because it reduces repeated requests, but it does not decide who is allowed to register. Monitor registration attempts and server logs, and tune limits for your traffic and deployment. Avoid copying old configuration snippets without checking your installed Synapse version: registration and identity-service options have changed over time.

What closing registration does—and does not—change

• It controls new local accounts. Disabling registration blocks the normal account-creation flow on your homeserver.
• It does not delete accounts. Existing users keep their accounts unless you separately suspend or deactivate them.
• It does not turn off federation. Users on other homeservers may still communicate with local users and rooms, subject to room membership and federation settings.
• It does not make a room invite-only. Room join rules are a separate setting; registration tokens do not replace room invitations.
• It does not necessarily block every provisioning path. Admin APIs, a configured shared secret, application services, and SSO account-creation settings need separate review.

A reverse proxy rule that hides a registration URL can be an additional network-layer control, but it is easy to break client flows and does not replace the homeserver’s own configuration. Use the application-level setting as the primary control and test the actual deployment after any proxy change.

Verify the result

1. Check the effective configuration source, including any container bind mount or generated configuration, for the intended registration values.
2. Restart Synapse and review startup logs for YAML errors or unsupported settings.
3. From a logged-out Matrix client, try to start a new registration. With registration disabled, the flow should not offer a usable public sign-up. With token-required registration enabled, a request without a valid token should not complete.
4. For token registration, test with a temporary one-use token and confirm that it completes only one account creation. Inspect the Admin API response for completed, pending, and expiry information.
5. Test a separately configured SSO path and any account-provisioning scripts. Confirm that they behave according to your access policy.

Do not use a real invitation token for a test account unless you intend to consume it. If the setting appears ineffective, first verify that you changed the file Synapse actually loads and that the service restarted. Then check for a shared registration secret, SSO auto-registration, or another trusted provisioning mechanism.

Official references

• Synapse 1.160 configuration manual: registration settings
• Synapse registration-token Admin API
• Synapse installation guide: registering a user
• Synapse shared-secret registration API
• Matrix Client-Server API specification

Synapse’s versioned configuration and Admin API documentation are the source of truth for option names and request fields. The instructions above do not assume a particular operating system, container image, reverse proxy, or Matrix client; confirm those deployment-specific details before applying changes.