telodendria/docs/user/admin/tokens.md
Jordan Bancino 2d30719be4 Implement Registration Token Administrator API (#43)
This pull request fully implements and documents all of the registration token administrator API endpoints.

**NOTE:** There is a memory leak when listing all of the registration tokens. Debug this before merging.
 
~~Closes~~ Supersedes #37.

Closes #26.

This pull request is based off of #37, which addresses #26. This pull makes a number of improvements to the logic, organization, and behavior of the API endpoints.

Co-authored-by: hatkid <daichi93100@gmail.com>
Co-authored-by: LoaD Accumulator <lda@freetards.xyz>
Co-authored-by: LoaD Accumulator <lda@noreply.git.telodendria.io>
Co-authored-by: lda <lda@freetards.xyz>
Co-authored-by: Load Accumulator <lda@freetards.xyz>
Reviewed-on: Telodendria/Telodendria#43
2023-11-10 09:30:53 -05:00

3.5 KiB

Administrator API: Registration Tokens

Telodendria implements registration tokens as specified by the Matrix specification. These tokens can be used for registration using the m.login.registration_token login type. This API provides a Telodendria administrator with a mechanism for generating and managing these tokens, which allows controlled registration on the homeserver.

It is generally safer than completely open registration to use registration tokens that either expire after a short period of time, or have a limited number of uses.

Registration Token

A registration token is represented by the following RegToken JSON object:

Field Type Description
name String The token identifier; what is used when registering.
created_by String The localpart of the user that created this token.
created_on Integer A timestamp of when the token was created.
expires_on Integer An expiration stamp, or 0 if the token never expires.
used Integer The number of times the token has been used.
uses Integer The total number of allowed uses, or -1 for unlimited.
grants [String] An array of privileges to grant users that register with this token as described in Privileges.

All endpoints in this API will operate on some variation of this structure. The remaining number of uses can be computed by performing the subtraction: uses - used. used should never be greater than uses or less than 0.

Example:

{
    "name": "q34jgapo8uq34hg",
    "created_by": "admin",
    "created_on": 1699467640000,
    "expires_on": 0,
    "used": 3,
    "uses": 5
}

API Endpoints

GET /_telodendria/admin/v1/tokens

Get a list of all registration tokens and information about them.

200 Response Format

Field Type Description
tokens [RegToken] An array of registration tokens.

GET /_telodendria/admin/v1/tokens/[name]

Get information about the specified registration token.

Request Parameters

Field Type Description
name String The name of the token, as it would be used to register a user.

200 Response Format

This endpoint returns a RegToken object that represents the server's record of the registration token.

POST /_telodendria/admin/v1/tokens

Create a new registration token.

Request Format

This endpoint accepts a RegToken object, as described above. If no name is provided, one will be randomly generated. Note that the fields created_by, created_on, and used are ignored and set by the server when this request is made. All other fields may be set by the request body.

200 Response Format

If the creation of the registration token was successful, a RegToken that represents the server's record of it is returned.

DELETE /_telodendria/admin/v1/tokens/[name]

Delete the specified registration token. It will no longer be usable for the registration of users. Any users that have completed the m.login.registration_token step but have not yet created their account should still be able to do so until their user-interactive auth session expires.

Request Parameters

Field Type Description
name String The name of the token, as it would be used to register a user.

200 Response Format

On success, this endpoint returns an empty JSON object.