Close Matrix Sign-Ups or Require Invite Tokens on Synapse

To stop public sign-ups on a self-hosted Matrix homeserver running Synapse, set enable_registration: false in homeserver.yaml and restart Synapse. If you want invited people to create accounts themselves, leave registration enabled but require registration tokens instead. Check the separate registration_shared_secret setting: anyone who knows it can still create accounts, including server administrators, even when ordinary registration is disabled.

Choose the right registration policy

The right setting depends on how new accounts should be created:

  • Private server, accounts provisioned by an administrator: disable public registration. Create users with Synapse’s register_new_matrix_user command or another approved administrative process.
  • Invite-only server, users register from Element or another client: enable registration and require a token. Give each person a limited-use token through a private channel.
  • Public server: registration tokens, CAPTCHA, or verified email/phone can reduce automated abuse, but they do not guarantee that every account is trustworthy.

This article covers Synapse, the most widely deployed self-hosted Matrix homeserver implementation. Other homeserver software has its own configuration. Synapse’s current configuration documentation says registration is disabled by default, and that registration tokens only work when registration itself is enabled. If you use Matrix Authentication Service (MAS), check its documentation for the corresponding registration controls; Synapse’s registration-token Admin API is disabled when MAS integration is enabled.

Disable public registration on Synapse

  1. Find the active configuration file. Common package installations use /etc/matrix-synapse/homeserver.yaml; container installations often mount the file under /data/homeserver.yaml. Use the path configured for your service rather than assuming one location.
  2. Back up the file, then set the registration flag. In the top-level YAML configuration, add or change the setting to:
    enable_registration: false
    If the key already exists, edit that entry instead of adding a duplicate. YAML indentation and duplicate keys can cause confusion, so keep the setting at the top level and preserve the file’s existing structure.
  3. Review the shared registration secret. Synapse’s registration_shared_secret (or registration_shared_secret_path) supports the administrative registration script. Synapse’s installation guide warns that someone with this secret can create standard or admin accounts even while public registration is off. Keep it private, restrict access to its file, and do not put it in a public repository, client configuration, or a message to invitees. If you do not use shared-secret registration, remove the setting only after confirming that no automation depends on it. You can instead create accounts using another supported administrator workflow.
  4. Validate and restart Synapse. Use the service manager, container orchestration, or deployment method that runs your server. For a systemd service commonly named matrix-synapse, an administrator might run:
    sudo systemctl restart matrix-synapse
    sudo systemctl status matrix-synapse --no-pager
    The exact service name differs across package and container deployments. Check the logs if the service fails to start; do not keep repeatedly editing a configuration file without resolving a reported YAML or configuration error.

Existing accounts and room access are not removed by disabling registration. The setting prevents new regular registrations through the client registration flow; it is not a user deletion or server deactivation control.

Allow sign-ups only with registration tokens

Use this option when you want invitees to complete sign-up themselves but do not want an open registration page. In homeserver.yaml, configure both settings:

enable_registration: true
registration_requires_token: true

Restart Synapse after saving. A token gate is not the same as disabling registration: people with valid tokens can create accounts. The Synapse configuration manual recommends anti-abuse controls when registration is enabled; choose a policy appropriate to your audience and operational capacity.

For Synapse versions that support the documented Registration Tokens Admin API, an administrator can create a single-use token. The following example uses a placeholder URL and access token; run it only from a trusted administrative environment, substitute your homeserver’s public base URL and an administrator access token, and protect shell history and logs:

curl -X POST "https://matrix.example.com/_synapse/admin/v1/registration_tokens/new" \
  -H "Authorization: Bearer YOUR_SERVER_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"uses_allowed":1}'

The response includes the generated token. Share that value privately with the intended user. Synapse’s API also supports an expiry time, measured in milliseconds since the Unix epoch; use the official API reference to calculate and set an expiry correctly for your deployment. A token with an omitted use limit or expiry defaults to unlimited uses and no expiry, so set limits deliberately. Administrators can list, update, or delete tokens through the same API. Do not paste an actual bearer token or registration token into a public issue or article.

Token management has a version and deployment boundary: consult the Admin API documentation matching your installed Synapse release. The current documentation notes that this Synapse API is unavailable when MAS integration is enabled; use the MAS Admin API or CLI in that setup.

Common configuration mistakes

  • Changing the wrong file: containers may read a mounted file, while the host has a separate copy. Confirm the path used by the running Synapse process.
  • Forgetting the restart: configuration changes are read by the service, so a successful text edit alone does not demonstrate that the new policy is active.
  • Assuming disabled registration blocks every route: a configured shared secret remains an account-creation path. Protect or remove it according to whether administrative automation needs it.
  • Enabling tokens but disabling registration: registration_requires_token does not independently turn registration on. Both flags must allow the intended flow.
  • Assuming invite-only tokens prevent all abuse: a leaked reusable token can be used by unintended people. Limit uses, set an expiry where practical, and distribute tokens privately.

Verify the result

After Synapse restarts, open your homeserver’s registration flow in a Matrix client using a signed-out session. For a closed server, the client should not offer a successful public sign-up, while existing users should still be able to sign in. For token-gated registration, try the flow with no token and confirm that it requests one; then use a test token in a controlled test account and confirm that the registration succeeds. Check Synapse logs and the Admin API token status if the result differs from the policy you intended. Avoid testing with the real invite token if doing so would consume its only allowed use.

Official references

Leave a Comment

Element Session Identity Warning: Verify Your Login Safely

Clear Element's unverified-session warning using a trusted device or recovery key, with checks that protect your encrypted chat history.

Stop ownCloud File Lock Timeouts with the Right Backend

Distinguish database lock contention from expired WebDAV locks, then choose and configure the right ownCloud 10 fix.

What to Check When ownCloud Web Opens to a Blank Page

What to Check When ownCloud Web Opens to a Blank Page

Trace a blank ownCloud Web screen to browser cache, missing web assets, service errors, or reverse-proxy URL settings with targeted checks.

Clear the ownCloud PHP Memory Warning in the Correct Runtime

Set ownCloud’s web PHP memory limit, restart the matching service, and verify the active value without confusing it with CLI settings or upload limits.

Troubleshoot ownCloud 10 MySQL Connection Failures

Find out whether MySQL, PHP, socket settings, or database permissions are blocking ownCloud 10, then verify a safe fix.

Set a Firm Expiration Limit for ownCloud Public Links

Set a Firm Expiration Limit for ownCloud Public Links

Make public link expiration mandatory in ownCloud Classic, set a maximum lifetime, and check existing shares that may need separate cleanup.

Add TOTP Two-Factor Login to ownCloud Infinite Scale with Keycloak

Add TOTP Two-Factor Login to ownCloud Infinite Scale with Keycloak

Enable TOTP through Keycloak, enroll users safely, and understand when Infinite Scale’s route-level MFA settings apply.

Restore ownCloud Sync by Matching the Client to Your Server

Check whether the issue is an OC10 and 7.x compatibility break or a damaged CSync journal, then apply the right fix without deleting synced files.

Put ownCloud on HTTPS with Let’s Encrypt and Nginx

Put ownCloud on HTTPS with Let’s Encrypt and Nginx

Choose HTTP-01 or DNS-01, configure an ownCloud reverse proxy, and verify Certbot renews HTTPS certificates automatically.

Connect ownCloud Infinite Scale to LDAP for User Sign-In

Configure oCIS LDAP sign-in, align user and group lookups, and verify TLS and schema settings before rollout.