forked from Telodendria/Telodendria
143 lines
5.2 KiB
Markdown
143 lines
5.2 KiB
Markdown
# 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.
|
|
- **APPSERVICE:** Allows a user to register and manage application
|
|
services.
|
|
- **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 and see 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/v1/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/v1/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/v1/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/v1/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.|
|
|
|