Homeserver Registration Token Checklist for Private Communities

By 4FreeForums Editors · Published October 31, 2026 · Sources linked below

Running a closed community requires firm boundaries around who can create an account on your server. When managing self-hosted infrastructure, leaving homeserver registration open invites spam accounts and unauthorized resource consumption. Homeserver administrators can restrict access while maintaining smooth onboarding by requiring administrative registration tokens for every new member.

1. Verify Homeserver Prerequisites and Configuration

Before issuing tokens, verify that your homeserver configuration enforces token-gated account creation. Registration token functionality was proposed in MSC3231 and stabilized in version 1.2 of the Matrix specification. Confirm the following setup steps before generating invitations:

• Server configuration directive: Ensure the registration_requires_token configuration option is enabled in your server configuration file. Without this setting active, registration attempts will not demand a valid token.
• Administrator credentials: Obtain an access_token belonging to a server administrator. Every administrative token request requires this credential to authenticate with the server endpoints, as described in the Synapse Registration Tokens documentation.
• Authentication service check: Note that this administrative API is disabled whenever Matrix Authentication Service (MAS) integration is turned on. If you utilize MAS integration, manage your tokens via the MAS Admin API or MAS CLI instead. Managed options like Element Admin within ESS Community and Pro also provide graphical management for this workflow.
• Architecture review: Compare your setup against the Synapse Matrix Homeserver Profile to ensure underlying services operate smoothly before handling registration traffic.

2. Checklist for Generating New Registration Tokens

When you onboard new staff members, moderators, or private community groups, generate unique tokens via HTTP POST requests directed to /_synapse/admin/v1/registration_tokens/new. Keep the following field requirements in mind when constructing the JSON request body:

• Custom token strings: If you specify a manual token, provide a string of no more than 64 characters consisting strictly of characters matched by the regex [A-Za-z0-9._~-]. If omitted, the server generates a random token automatically.
• Token string length: If you choose automated generation, the optional length parameter controls the length of the randomly generated string. It must be set to an integer between 1 and 64 inclusive, with the default set to 16.
• Usage caps: Define uses_allowed as an integer representing the exact number of times a token can successfully complete registration before becoming invalid. Setting this parameter to null creates a token with unlimited uses.
• Expiration timestamps: Specify an optional expiry_time as an integer representing milliseconds since 1970-01-01 00:00:00 UTC (the start of the Unix epoch). For example, you can calculate an upcoming timestamp using date '+%s000' -d 'tomorrow'. If left null, the token will not expire.

3. Audit Active and Expired Tokens via the Admin API

Regular security audits help you monitor pending onboarding flows and track exhausted invitation links. Auditing tokens forms a core part of operational hygiene alongside overall Forum Admin Security practices. To audit your token roster, issue a GET request to /_synapse/admin/v1/registration_tokens.

The response returns a top-level JSON object containing a registration_tokens array. Each token entry provides four essential tracking fields:

• uses_allowed: The overall number of completions permitted before the token turns invalid.
• pending: The number of active authentication attempts underway. When an applicant uses the token to authenticate, the homeserver increments pending to block concurrent attempts from exceeding the quota. If the user successfully finishes registration, pending decrements while completed increments.
• completed: The count of successfully finished registrations completed with that token.
• expiry_time: The expiration timestamp in milliseconds since the Unix epoch, or null if permanent. Admins can convert this value to readable UTC text using the system command date -d '@1625394937' after stripping the millisecond zeros.

To inspect a single token directly, issue a GET request to /_synapse/admin/v1/registration_tokens/<token>. If you query a token identifier that does not exist, the server returns an HTTP 404 Not Found error with the code M_NOT_FOUND.

4. Update Token Limits and Handle Server Revocations

Community needs shift over time, requiring administrators to extend expiration windows, adjust allowances, or instantly disable invitations. You can modify existing records via a PUT request sent to /_synapse/admin/v1/registration_tokens/<token>:

• Immediate invalidation without deletion: You can instantly revoke a compromised or surplus token without wiping its audit trail by updating uses_allowed to 0.
• Extending or clearing expirations: You can submit a new millisecond timestamp to extend an onboarding window, or submit null to clear an expiration date entirely.
• Permanent removal: If you prefer to scrub a token from the server, submit a DELETE request to /_synapse/admin/v1/registration_tokens/<token>. A successful deletion returns an HTTP 200 OK status containing an empty JSON object.
• Auditing query filtering: When running token reviews, use the valid URL query parameter on the listing endpoint. Setting valid=true restricts results solely to usable tokens, whereas valid=false filters for records that have expired or exhausted all permitted completions, per the Synapse Registration Tokens documentation.

Sources

• Synapse Registration Tokens Documentation

Published October 31, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.