forked from Telodendria/Telodendria
Jordan Bancino
2d30719be4
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
106 lines
No EOL
3.5 KiB
Markdown
106 lines
No EOL
3.5 KiB
Markdown
# 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](privileges.md). |
|
|
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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. |