Add privileges documentation.

This commit is contained in:
Jordan Bancino 2023-09-08 23:26:47 -04:00
parent 9e2f047e82
commit 043c2e9e33
2 changed files with 155 additions and 0 deletions

View file

@ -20,3 +20,17 @@ request.
- [Server Statistics](stats.md) - [Server Statistics](stats.md)
- [Process Control](proc.md) - [Process Control](proc.md)
## API Conventions
Unless otherwise indicated, HTTP response codes that are not `200 Ok`
will be accompanied by a standard Matrix API error. Consult the Matrix
specification for the format of these errors. The following error
conditions are assumed to be possible for all API endpoints listed
in the Administrator API documentation:
| Response Code | Description |
|---------------|-------------|
| 400 | The user is not authenticated, did not provide a valid JSON object, or provided a JSON object with invalid or missing parameters.|
| 403 | The user does not have the privileges necessary to carry out the requested action.|
| 500 | A fatal server error occurred. Check the logs for more information.|

View file

@ -0,0 +1,141 @@
# Administrator API: Privileges
This document describes the privilege model and the API endpoints that
allow administrators to modify privileges for users.
## List Of Privileges
A local user can have any of the following privileges. Unless otherwise
indicated, these privileges only grant access to certain parts of the
administrator API; the regular Matrix API is unaffected.
- **DEACTIVATE:** Allows a user to deactivate any other local users.
- **ISSUE_TOKENS:** Allows a user to create, modify, and delete
registration tokens.
- **CONFIG:** Allows a user to modify the Telodendria server daemon's
configuration.
- **GRANT_PRIVILEGES:** Allows a user to modify his or her own
privileges or the privileges of other local users.
- **ALIAS:** Allows a user to modify room aliases created by other
users. By default, users can only manage their own room aliases, but
an administrator may wish to take over an alias or remove an offensive
alias.
- **PROC_CONTROL:** Allows a user to get statistics on the running
process, as well as shutdown and resetart the Telodendria daemon
itself. Typically this will pair well with **CONFIG**, because there
are certain configuration options that require the process to be
restarted to take full effect.
There is also a special "pseudo-privilege":
- **ALL:* Grants a user all of the aforementioned privileges, as well
as privileges that do not yet exist. That is, if an update to
Telodendria adds more privileges, users with this privilege will
automatically gain those new privileges in addition to having all the
existing privileges. This privilege should only be used with
fully-trusted users. It is typical for a server administrator to not
fully trust anyone else, and be the only one that holds an account with
this privilege level.
## API Endpoints
The following API endpoints are implemented for managing privileges.
### **GET** `/_telodendria/admin/privileges/[localpart]`
Retrieve the permissions for a user. If the localpart is omitted, then
retrieve the privileges for the user that owns the access token being
used. Note that the owner of the access token must have the
**GRANT_PRIVILEGES** privilege to use this endpoint.
| Requires Token | Rate Limited |
|----------------|--------------|
| Yes | Yes |
| Response Code | Description |
|---------------|-------------|
| 200 | The privileges were successfully retrieved.|
#### 200 Response Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
### **POST** `/_telodendria/admin/privileges/[localpart]`
Update the privileges of a local user by replacing the privileges array
with the one specified in the request. Like the **GET** version of this
endpoint, the localpart can be omitted to operate on the user that
owns the access token.
| Requires Token | Rate Limited |
|----------------|--------------|
| Yes | Yes |
| Response Code | Description |
|---------------|-------------|
| 200 | The privileges were successfully replaced.|
#### Request Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
#### 200 Response Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
### **PUT** `/_telodendria/admin/privileges/[localpart]
Update the privileges of a local user by adding the privileges
specified in the request to the users existing privileges.
| Requires Token | Rate Limited |
|----------------|--------------|
| Yes | Yes |
| Response Code | Description |
|---------------|-------------|
| 200 | The privileges were successfully added.|
#### Request Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
#### 200 Response Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
### **DELETE** `/_telodendria/admin/privileges/[localpart]`
Update the privileges of a local user by removing the privileges
specified in the request from the user's existing privileges.
| Requires Token | Rate Limited |
|----------------|--------------|
| Yes | Yes |
| Response Code | Description |
|---------------|-------------|
| 200 | The privileges were successfully removed.|
#### Request Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|
#### 200 Response Format
| Field | Type | Description |
|-------|------|-------------|
| `privileges` | `Array` | An array of privileges, as described above. The privileges are encoded as JSON strings.|