forked from lda/telodendria
parent
fd28f97449
commit
2b43a93524
1 changed files with 0 additions and 453 deletions
|
|
@ -1,453 +0,0 @@
|
||||||
.Dd $Mdocdate: April 16 2023 $
|
|
||||||
.Dt ADMIN 7
|
|
||||||
.Os Telodendria Project
|
|
||||||
.Sh NAME
|
|
||||||
.Nm Admin
|
|
||||||
.Nd Suggestion on a Telodendria Admin API
|
|
||||||
.Sh DESCRIPTION
|
|
||||||
.Pp
|
|
||||||
This is a suggestion of how the admin API should work; it is subject
|
|
||||||
to heavy changes.
|
|
||||||
.Pp
|
|
||||||
It also acts as a suggestion on how suggestions should be written. It
|
|
||||||
might not be accepted, or the format might be changed heavily.
|
|
||||||
.Ss Admin Users
|
|
||||||
.Pp
|
|
||||||
Like in Synapse, there should be a field dictating if the user is an
|
|
||||||
admin, and unlike Synapse, there should be privilege levels.
|
|
||||||
.Pp
|
|
||||||
In the
|
|
||||||
.Pa users/[user].json
|
|
||||||
file, there should be a field called
|
|
||||||
.Dv privileges
|
|
||||||
which contains a list of strings.
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"devices": {
|
|
||||||
"foobar": { ... }
|
|
||||||
},
|
|
||||||
"salt": "salt goes here",
|
|
||||||
"deactivated": false,
|
|
||||||
"createdOn": 1700000000000,
|
|
||||||
"password": "hash goes here",
|
|
||||||
"privileges": [
|
|
||||||
"DEACTIVATE",
|
|
||||||
"ISSUE_TOKENS"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Privileges list
|
|
||||||
.Pp
|
|
||||||
Here are all of the admin privileges a user can have:
|
|
||||||
.Bl -tag -width Ds
|
|
||||||
.It Dv DEACTIVATE
|
|
||||||
This allows an user to deactivate any users using
|
|
||||||
the
|
|
||||||
.Em DELETE
|
|
||||||
/_telodendria/admin/disable/[localpart]
|
|
||||||
endpoint.
|
|
||||||
.It Dv ISSUE_TOKENS
|
|
||||||
This allows users to create, modify and delete registration
|
|
||||||
tokens.
|
|
||||||
.It Dv CONFIG
|
|
||||||
Users with this privilege can modify Telodendria's configuration.
|
|
||||||
.It Dv GRANT_PRIVILEGES
|
|
||||||
Users with this privilege can modify their own privileges or
|
|
||||||
the privileges of others.
|
|
||||||
.It Dv ALL
|
|
||||||
Users with this privilege can use
|
|
||||||
.Em any
|
|
||||||
admin endpoint(and some others).
|
|
||||||
.Em THIS PRIVILEGE SHOULD ONLY BE USED WITH TRUSTED USERS.
|
|
||||||
.Sh API ENDPOINTS
|
|
||||||
.Ss Sy GET No /_telodendria/admin/privileges
|
|
||||||
.Pp
|
|
||||||
Get the priviledges of the user that owns the provided access token.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Requires Token;Rate Limited
|
|
||||||
Yes;Yes
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
200;Privileges successfully returned.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
privileges;list;The same data structure described in the database.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"privileges": [
|
|
||||||
"DEACTIVATE",
|
|
||||||
"REMOVE_DEVICES"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy DELETE No /_telodendria/admin/deactivate/[localpart]
|
|
||||||
.Pp
|
|
||||||
Deactivates a local user, optionally with a reason.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;DEACTIVATE
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
Request JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l l.
|
|
||||||
Field;Type;Description;Required
|
|
||||||
reason;string;A reason why the user was deactivated;No
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
Request Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"reason": "Being mean in a lot of rooms."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
200;User was successfully deactivated.
|
|
||||||
403;User does not have the DEACTIVATE permission.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
user;localpart;The deactivated user's localpart
|
|
||||||
reason;string;T{
|
|
||||||
The reason why the user was deactivated.
|
|
||||||
Defaults to: ``Deactivated by admin''
|
|
||||||
T}
|
|
||||||
banned_by;localpart;T{
|
|
||||||
The localpart of the admin who deactivated the user.
|
|
||||||
T}
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
errcode;string;Set to ``M_FORBIDDEN''
|
|
||||||
error;string;Human-readable explanation of the privilege issue.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"user": "evan",
|
|
||||||
"reason": "Being mean in a lot of rooms",
|
|
||||||
"banned_by": "alice"
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
403 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy PUT No /_telodendria/admin/deactivate/[localpart]
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;DEACTIVATE
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.Em Description:
|
|
||||||
Reactivates a local user.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
204;User was successfully reactivated.
|
|
||||||
403;User does not have the DEACTIVATE permission.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
errcode;string;Set to ``M_FORBIDDEN''
|
|
||||||
error;string;Human-readable explanation of the privilege issue.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
403 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy GET No /_telodendria/admin/tokens
|
|
||||||
.Pp
|
|
||||||
Gets a list of
|
|
||||||
.Em all
|
|
||||||
tokens present, and additional information.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;ISSUE_TOKENS
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
200;Token list was successfully retrieved.
|
|
||||||
403;User does not have the ISSUE_TOKENS permission.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
tokens;list[TokenInfo];A list of tokens and other information.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.Dv TokenInfo
|
|
||||||
JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
name;string;The token's name.
|
|
||||||
created_by;localpart;The user who has created token.
|
|
||||||
created_on;timestamp;The creation date of the token.
|
|
||||||
expires_on;timestamp;T{
|
|
||||||
The token's expiration date, or 0 if it does not
|
|
||||||
expire.
|
|
||||||
T}
|
|
||||||
used;integer;The number of times the token was used.
|
|
||||||
uses;integer;T{
|
|
||||||
The number of uses remaining for the token, or -1 if
|
|
||||||
there are an unlimited number of uses remaining.
|
|
||||||
T}
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
errcode;string;Set to ``M_FORBIDDEN''
|
|
||||||
error;string;Human-readable explanation of the privilege issue.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"tokens": [
|
|
||||||
{
|
|
||||||
"name": "forbob",
|
|
||||||
"created_by": "alice",
|
|
||||||
"created_on": 1234567890123,
|
|
||||||
"expires_on": 2147483647000,
|
|
||||||
"used": 1,
|
|
||||||
"uses": 3
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy GET No /_telodendria/admin/tokens/[token]
|
|
||||||
.Pp
|
|
||||||
Returns information about a specific registration token.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;ISSUE_TOKENS
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
200;Token information successfully retrieved.
|
|
||||||
403;User does not have the ISSUE_TOKENS permission.
|
|
||||||
404;The specified token does not exist.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
name;string;The token's name.
|
|
||||||
created_by;localpart;The user who created the token.
|
|
||||||
created_on;timestamp;The creation date of the token.
|
|
||||||
expires_on;timestamp;The token's expiration date, if provided.
|
|
||||||
used;integer;The number of times the token was used.
|
|
||||||
uses;integer;T{
|
|
||||||
The number of remaining uses for the token, if set.
|
|
||||||
Otherwise, there are unlimited uses remaining.
|
|
||||||
T}
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"name": "forbob",
|
|
||||||
"created_by": "alice",
|
|
||||||
"created_on": 1234567890123,
|
|
||||||
"used": 1,
|
|
||||||
"uses": 3
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy POST No /_telodendria/admin/tokens
|
|
||||||
.Pp
|
|
||||||
Adds a registration token, and setup expiry date and max uses.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;ISSUE_TOKENS
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
Request JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l l.
|
|
||||||
Field;Type;Description;Required
|
|
||||||
lifetime;timestamp;T{
|
|
||||||
How long this token should be good for
|
|
||||||
T};NO
|
|
||||||
max_uses;integer;T{
|
|
||||||
The maximum number of uses for this token
|
|
||||||
T};NO
|
|
||||||
name;string;T{
|
|
||||||
A name for the token. If none is provided, then a name
|
|
||||||
is randomly generated.
|
|
||||||
T};NO
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
Request Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"name": "OnlyClownsM7iAhUJD",
|
|
||||||
"expires": 2147484637000,
|
|
||||||
"max_uses": 5
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
200;Token was successfully created.
|
|
||||||
403;User does not have the ISSUE_TOKENS permission.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response JSON Format:
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Field;Type;Description
|
|
||||||
name;string;The token's name.
|
|
||||||
created_by;localpart;The user who created the token.
|
|
||||||
created_on;timestamp;The creation date of the token.
|
|
||||||
expires_on;timestamp;T{
|
|
||||||
The token's expiration date, if set. If not set, the
|
|
||||||
token never expires.
|
|
||||||
T}
|
|
||||||
used;integer;The number of times the token was used.
|
|
||||||
uses;integer;T{
|
|
||||||
The number of uses remaining for the token, if set. If
|
|
||||||
not set, the token has an unlimited number of uses.
|
|
||||||
T}
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
200 Response Example:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"name": "OnlyClownsM7iAhUJD",
|
|
||||||
"created_by": "donald",
|
|
||||||
"created_on": 1234567890123,
|
|
||||||
"expires_on": 2147484637000,
|
|
||||||
"used": 0,
|
|
||||||
"uses": 5
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
.Ss Sy DELETE No /_telodendria/admin/tokens/[tokenname]
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l l.
|
|
||||||
Requires Token;Rate Limited;Permissions
|
|
||||||
Yes;Yes;ISSUE_TOKENS
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
.Em Description:
|
|
||||||
Deletes an existing registration token.
|
|
||||||
.Pp
|
|
||||||
.TS
|
|
||||||
tab(;) allbox center;
|
|
||||||
l l.
|
|
||||||
Error Response;Description
|
|
||||||
204;Token was successfully deleted.
|
|
||||||
403;User does not have the ISSUE_TOKENS permission.
|
|
||||||
.TE
|
|
||||||
.Pp
|
|
||||||
403 Response JSON Format:
|
|
||||||
.Bd -literal -offset indent
|
|
||||||
{
|
|
||||||
"errcode": "M_FORBIDDEN",
|
|
||||||
"error": "Forbidden access. Bad permissions or not authenticated."
|
|
||||||
}
|
|
||||||
.Ed
|
|
||||||
Loading…
Reference in a new issue