forked from lda/telodendria
Add privileges documentation.
This commit is contained in:
parent
9e2f047e82
commit
043c2e9e33
2 changed files with 155 additions and 0 deletions
|
|
@ -20,3 +20,17 @@ request.
|
|||
- [Server Statistics](stats.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.|
|
||||
|
||||
|
|
|
|||
141
docs/user/admin/privileges.md
Normal file
141
docs/user/admin/privileges.md
Normal 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.|
|
||||
|
||||
Loading…
Reference in a new issue