forked from Telodendria/Telodendria
Add privileges documentation.
This commit is contained in:
parent
20c4a4d0fb
commit
73dd12ef7e
2 changed files with 155 additions and 0 deletions
|
|
@ -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.|
|
||||||
|
|
||||||
|
|
|
||||||
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