Add privileges documentation.

docs/user/admin/README.md

@@ -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.|
+

docs/user/admin/privileges.md

@@ -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.|
+