forked from Telodendria/Telodendria
Jordan Bancino
58dae3a0c9
If an admin wants to create a user, he or she should have the ISSUE_TOKEN privilege. The admin can use that to create a one-time registration token, and then just use the regular registration API with that token.
433 lines
14 KiB
Markdown
433 lines
14 KiB
Markdown
# #1: Suggestion on a Telodendria Admin API.
|
|
This is a suggestion of how the admin API should work; it is subject to
|
|
heavy changes.
|
|
|
|
It also acts as a suggestion on how suggestions should be written. It
|
|
might not be accepted, or the format might be changed heavily.
|
|
|
|
## "Admin" users.
|
|
Like in Synapse, there should be a field dictating if the user is an
|
|
admin, and unlike Synapse, there should be privilege levels.
|
|
|
|
In the `[dataroot]/users/[user].json` file, there should be a field
|
|
called `"privileges"` which contains a list of strings.
|
|
|
|
```json
|
|
{
|
|
"devices": {
|
|
"foobar": { ... }
|
|
},
|
|
"salt": "salt goes here",
|
|
"deactivated": false,
|
|
"createdOn": 1700000000000,
|
|
"password": "hash goes here",
|
|
"privileges": [
|
|
"DEACTIVATE",
|
|
"ISSUE_TOKENS"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Privileges list
|
|
Here are all of the admin privileges a user can have:
|
|
|
|
- DEACTIVATE:
|
|
This allows an user to deactivate/reactivate any users using
|
|
the DELETE /_telodendria/admin/disable/[localpart] endpoint
|
|
|
|
- ISSUE_TOKENS:
|
|
This allows users to create, modify and delete registration
|
|
tokens.
|
|
|
|
- ALL:
|
|
Users with this privilege can use *any* admin endpoint(and some
|
|
others)
|
|
|
|
**THIS PRIVILEGE SHOULD ONLY BE USED WITH *TRUSTED* USERS.**
|
|
|
|
## Admin endpoints
|
|
|
|
### GET `/_telodendria/admin/privileges`
|
|
|
|
Get the priviledges of the user that owns the provided access token.
|
|
|
|
|Requires token|Rate limited|
|
|
|--------------|------------|
|
|
|YES |YES |
|
|
|
|
|
|
|Error response|Description |
|
|
|--------------|------------------------|
|
|
|200 |Privileges successfully |
|
|
| |returned. |
|
|
|
|
200 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|-----------|-------------------------------------------------|
|
|
|privileges |list |The same data structure as in `users/[user].json`|
|
|
|
|
200 Response Example:
|
|
```json
|
|
{
|
|
"privileges": [
|
|
"DEACTIVATE",
|
|
"REMOVE_DEVICES"
|
|
]
|
|
}
|
|
```
|
|
|
|
### DELETE `/_telodendria/admin/deactivate/[localpart]`
|
|
|
|
Deactivates a local user, optionally with a reason.
|
|
|
|
|Requires token|Rate limited|Permissions|
|
|
|--------------|------------|-----------|
|
|
|YES |YES |DEACTIVATE |
|
|
|
|
Request JSON Format:
|
|
|
|
|Field |Type |Description |Required|
|
|
|-----------|-----------|---------------------|--------|
|
|
|reason |string |A reason why the |NO |
|
|
| | |user was deactivated.| |
|
|
|
|
Request Example:
|
|
```json
|
|
{
|
|
"reason": "Being mean in a lot of rooms."
|
|
}
|
|
```
|
|
|
|
|Error response|Description |
|
|
|--------------|------------------------|
|
|
|200 |User was sucessfully |
|
|
| |deactivated. |
|
|
|--------------|------------------------|
|
|
|403 |User does not have the |
|
|
| |DEACTIVATE permission |
|
|
|
|
200 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|-----------|-----------------------|
|
|
|user |localpart |The deactivated user's |
|
|
| | |localpart |
|
|
|-----------|-----------|-----------------------|
|
|
|reason |string |The reason the user |
|
|
| | |was deactivacted. |
|
|
| | |Defaults to: |
|
|
| | |"Deactivated by admin" |
|
|
|-----------|-----------|-----------------------|
|
|
|banned_by |localpart |The localpart of the |
|
|
| | |admin who deactivated |
|
|
| | |the user.
|
|
|
|
403 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|-----------|-----------------------|
|
|
|errcode |string |Set to "M_FORBIDDEN" |
|
|
|-----------|-----------|-----------------------|
|
|
|error |string |Human-readable explain-|
|
|
| | |ation of the privilege |
|
|
| | |issue. |
|
|
|
|
200 Response Example:
|
|
```json
|
|
{
|
|
"user": "evan",
|
|
"reason": "Being mean in a lot of rooms",
|
|
"banned_by": "alice"
|
|
}
|
|
```
|
|
|
|
403 Response Example:
|
|
```
|
|
{
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
}
|
|
```
|
|
|
|
### PUT `/_telodendria/admin/deactivate/[localpart]`
|
|
|
|
|Requires token|Rate limited|Permissions|
|
|
|--------------|------------|-----------|
|
|
|YES |YES |DEACTIVATE |
|
|
|
|
Description:
|
|
Reactivates a local user.
|
|
|
|
|Error response|Description |
|
|
|--------------|------------------------|
|
|
|204 |User was sucessfully |
|
|
| |reactivated. |
|
|
|--------------|------------------------|
|
|
|403 |User does not have the |
|
|
| |DEACTIVATE permission |
|
|
|
|
403 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|-----------|-----------------------|
|
|
|errcode |string |Set to "M_FORBIDDEN" |
|
|
|-----------|-----------|-----------------------|
|
|
|error |string |Human-readable explain-|
|
|
| | |ation of the privilege |
|
|
| | |issue. |
|
|
|
|
403 Response Example:
|
|
```
|
|
{
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
}
|
|
```
|
|
|
|
### GET `/_telodendria/admin/tokens`
|
|
|
|
Gets a list of *all* tokens present, and additional information.
|
|
|
|
|Requires token|Rate limited|Permissions |
|
|
|--------------|------------|------------|
|
|
|YES |YES |ISSUE_TOKENS|
|
|
|
|
|Error response|Description |
|
|
|--------------|---------------------------|
|
|
|200 |Token list was sucessfully |
|
|
| |retrieved |
|
|
|--------------|---------------------------|
|
|
|403 |User does not have the |
|
|
| |ISSUE_TOKENS permission. |
|
|
|
|
200 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|----------------------|-----------------------|
|
|
|tokens |list[`TokenInfo`] |A list of tokens and |
|
|
| | |other information. |
|
|
|
|
`TokenInfo` JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|----------------------|-------------------------|
|
|
|name |string |The token's name. |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_by |localpart |The user who has created |
|
|
| | |the token's localpart |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_on |timestamp |The creation date of the |
|
|
| | |token. |
|
|
|-----------|----------------------|-------------------------|
|
|
|expires_on |timestamp |The token's expiry date |
|
|
| | |NOTE: If token does not |
|
|
| | |expire, it is set to 0 |
|
|
|-----------|----------------------|-------------------------|
|
|
|used |integer |The number of times the |
|
|
| | |token was used |
|
|
|-----------|----------------------|-------------------------|
|
|
|uses |integer |The number of uses for a |
|
|
| | |token. |
|
|
| | |NOTE: If token has unli- |
|
|
| | |mited mumber of uses, |
|
|
| | |set to 0 |
|
|
|
|
403 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|-----------|-----------------------|
|
|
|errcode |string |Set to "M_FORBIDDEN" |
|
|
|-----------|-----------|-----------------------|
|
|
|error |string |Human-readable explain-|
|
|
| | |ation of the privilege |
|
|
| | |issue. |
|
|
|
|
200 Response Example:
|
|
```json
|
|
{
|
|
"tokens": [
|
|
{
|
|
"name": "forbob",
|
|
"created_by": "alice",
|
|
"created_on": 1234567890123,
|
|
"expires_on": 2147483647000,
|
|
"used": 1,
|
|
"uses": 3
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
403 Response JSON Format:
|
|
```json
|
|
{
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
}
|
|
```
|
|
|
|
### GET `/_telodendria/admin/tokens/[token]`
|
|
|
|
Returns information about a specific registration token.
|
|
|
|
|Requires token|Rate limited|Permissions |
|
|
|--------------|------------|------------|
|
|
|YES |YES |ISSUE_TOKENS|
|
|
|
|
|error response|description |
|
|
|--------------|---------------------------|
|
|
|200 |token info was sucessfully |
|
|
| |retrieved |
|
|
|--------------|---------------------------|
|
|
|403 |user does not have the |
|
|
| |ISSUE_TOKENS permission. |
|
|
|--------------|---------------------------|
|
|
|404 |Token does not exist. |
|
|
|
|
200 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|----------------------|-------------------------|
|
|
|name |string |The token's name. |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_by |localpart |The user who has created |
|
|
| | |the token's localpart |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_on |timestamp |The creation date of the |
|
|
| | |token. |
|
|
|-----------|----------------------|-------------------------|
|
|
|expires_on |timestamp |The token's expiry date |
|
|
| | |NOTE: If token does not |
|
|
| | |expire, it is not set. |
|
|
|-----------|----------------------|-------------------------|
|
|
|used |integer |The number of times the |
|
|
| | |token was used |
|
|
|-----------|----------------------|-------------------------|
|
|
|uses |integer |The number of uses for |
|
|
| | |the token. |
|
|
| | |NOTE: If token has unli- |
|
|
| | |mited mumber of uses, it |
|
|
| | |is not set. |
|
|
|
|
200 Response Example:
|
|
```json
|
|
{
|
|
"name": "forbob",
|
|
"created_by": "alice",
|
|
"created_on": 1234567890123,
|
|
"used": 1,
|
|
"uses": 3
|
|
}
|
|
```
|
|
|
|
### POST `/_telodendria/admin/tokens`
|
|
|
|
Adds a registration token, and setup expiry date and max uses.
|
|
|
|
|Requires token|Rate limited|Permissions |
|
|
|--------------|------------|------------|
|
|
|YES |YES |ISSUE_TOKENS|
|
|
|
|
Request JSON Format:
|
|
|
|
|Field |Type |Description |Required|
|
|
|-----------|-----------|----------------------|--------|
|
|
|expires |timestamp |The timestamp for this|NO |
|
|
| | |token's expiry. | |
|
|
|-----------|-----------|----------------------|--------|
|
|
|max_uses |integer |The maximum number of |NO |
|
|
| | |uses for this token | |
|
|
|-----------|-----------|----------------------|--------|
|
|
|name |string |A name for the token. |NO |
|
|
| | |If none is set, a ran-| |
|
|
| | |domly generated string| |
|
|
| | |is made. | |
|
|
|
|
Request Example:
|
|
```json
|
|
{
|
|
"name": "OnlyClownsM7iAhUJD",
|
|
"expires": 2147484637000,
|
|
"max_uses": 5
|
|
}
|
|
```
|
|
|
|
|Error response|Description |
|
|
|--------------|---------------------------|
|
|
|200 |Token was sucessfully crea-|
|
|
| |ted |
|
|
|--------------|---------------------------|
|
|
|403 |User does not have the |
|
|
| |ISSUE_TOKENS permission. |
|
|
|
|
200 Response JSON Format:
|
|
|
|
|Field |Type |Description |
|
|
|-----------|----------------------|-------------------------|
|
|
|name |string |The token's name. |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_by |localpart |The user who has created |
|
|
| | |the token's localpart |
|
|
|-----------|----------------------|-------------------------|
|
|
|created_on |timestamp |The creation date of the |
|
|
| | |token. |
|
|
|-----------|----------------------|-------------------------|
|
|
|expires_on |timestamp |The token's expiry date |
|
|
| | |NOTE: If token does not |
|
|
| | |expire, it is not set. |
|
|
|-----------|----------------------|-------------------------|
|
|
|used |integer |The number of times the |
|
|
| | |token was used |
|
|
|-----------|----------------------|-------------------------|
|
|
|uses |integer |The number of uses for |
|
|
| | |the token. |
|
|
| | |NOTE: If token has unli- |
|
|
| | |mited mumber of uses, it |
|
|
| | |is not set. |
|
|
|
|
200 Response Example:
|
|
```json
|
|
{
|
|
"name": "OnlyClownsM7iAhUJD",
|
|
"created_by": "donald",
|
|
"created_on": 1234567890123,
|
|
"expires_on": 2147484637000,
|
|
"used": 0,
|
|
"uses": 5
|
|
}
|
|
```
|
|
|
|
403 Response JSON Format:
|
|
```json
|
|
{
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
}
|
|
```
|
|
|
|
### DELETE /_telodendria/admin/tokens/[tokenname]
|
|
|
|
|Requires token|Rate limited|Permissions |
|
|
|--------------|------------|------------|
|
|
|YES |YES |ISSUE_TOKENS|
|
|
|
|
Description:
|
|
Deletes an existing registration token.
|
|
|
|
|Error response|Description |
|
|
|--------------|---------------------------|
|
|
|204 |Token was sucessfully dele-|
|
|
| |ted |
|
|
|--------------|---------------------------|
|
|
|403 |User does not have the |
|
|
| |ISSUE_TOKENS permission. |
|
|
|
|
403 Response JSON Format:
|
|
```json
|
|
{
|
|
"errcode": "M_FORBIDDEN",
|
|
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
}
|
|
```
|
|
|