TELODENDRIA-ADMIN(7) Miscellaneous Information Manual TELODENDRIA-ADMIN(7)

telodendria-admin — Administrator API documention.

Telodendria provides an administrator API that allows for administrator control over the homeserver. This includes profiling and examining the state of Telodendria, as well as managing users and media.

Like Synapse, Telodendria supports designating specific users as administrators. However, unlike Synapse, it uses a more finely-grained privilege model that allows a server administrator to designate specific administration tasks to other users while not compromising and granting them full administrative access to the server.

To authenticate with the administrator API, simply use a regular access token.

Here are all of the privileges a local user can have. Unless otherwise specified, these privileges only grant access to certain parts of the administrator API; the regular Matrix API is unaffected.

Allows a user to deactivate any other local users.
Allows a user to create, modify, and delete registration tokens.
Allows a user to modify the Telodendria server daemon's configuration.
Allows a user to modify his or her own privileges or the privileges of other local users.
Allows a user to get statistics on the running process, as well as shutdown and restart the Telodendria daemon itself. Typically this will pair well with CONFIG, because there are certain configuration options that require the process to be restarted.

There is also a special ``pseudo-privilege'':

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 of 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.

The following API endpoints are implemented for the installed version of Telodendria.

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 of the endpoints listed here:

Response Code Description
400 The user is not authenticated, did not provide a valid JSON object, or provided a JSON object with invalid parameters.
403 The user does not have the privileges necessary to carry out the specified action.
500 A fatal server error occured. Check the logs for more information.

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.

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 represented as strings in JSON.

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 represented as strings in JSON.

200 Response Format:

Field Type Description
privileges Array An array of privileges, as described above. The privileges are represented as strings in JSON.

/_telodendria/admin/privileges/[localpart]

Update the privileges of a local user by adding the privileges specified in the request to the user's existing privileges.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The requested privileges were successfully added.

Request Format:

Field Type Description
privileges Array An array of privileges, as described above. The privileges are represented as strings in JSON.

200 Response Format:

Field Type Description
privileges Array An array of privileges, as described above. The privileges are represented as strings in JSON.

/_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 requested privileges were successfully removed.

Request Format:

Field Type Description
privileges Array An array of privileges, as described above. The privileges are represented as strings in JSON.

200 Response Format:

Field Type Description
privileges Array An array of privileges, as described above. The privileges are represented as strings in JSON.

Installs a new configuration. It validates the request body, ensuring it is a proper configuration, then replaces the existing configuration with the new one.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The new configuration was successfully installed.

Consult the telodendria-config(7) manual page for a full description of the configuration object that should be submitted. That page lists all the fields, and notes which ones are required.

200 Response Format:

Field Type Description
restart_required Boolean Whether or not the process needs to be restarted to finish applying the configuration. If this is true, the restart endpoint may be used.

Retrieve the current configuration.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The current configuration was successfully retrieved.

Consult the telodendria-config(7) manual page for a full description of the configuration object that is returned. Note that this is the same object that was submitted using the POST version of this endpoint, otherwise it is the default configuration.

Retrieve statistics about the currently running Telodendria process.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The server statistics were successfully retrieved.

200 Response Format:

Field Type Description
memory_allocated Integer The total amount of memory allocated, measured in bytes.
version String The current version of Telodendria.

Restart the Telodendria daemon cleanly. This endpoint will respond immediately after signaling to the daemon that it should be restarted as soon as possible. Note that the restart may not happen instantaneously, as Telodendria will finish processing all current requests before restarting. Also note that this is not a ``true'' restart; the process does not exit and restart, rather, Telodendria simply tears down its state, and then jumps back to the beginning of its code and starts over.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The restart request was successfully sent.

On success, this endpoint simply returns an empty JSON object.

Shut down the Telodendria process cleanly. This endpoint will respond immediately after signaling to the daemon that it should be shut down as soon as possible. Note that the shutdown may not happen instantaneously, as Telodnedria will finish processing all current requests before shutting down. Also note that once shut down, Telodendria may be automatically restarted by the system's service manager, otherwise, it will have to be manually restarted. This is a ``true'' shutdown, the Telodendria process exits as soon as possible.

Requires Token Rate Limited
Yes Yes
Response Code Description
200 The shutdown request was successfully sent.

On success, this endpoint simply returns an empty JSON object.

telodendria-config(7), telodendria-setup(7)

April 20, 2023 Telodendria Project