This repository has been archived by the owner on Apr 26, 2024. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 2.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Convert admin api docs to markdown (#10089)
So that they render nicely in mdbook (see #10086), and so that we no longer have a mix of structured text languages in our documentation (excluding files outside of `docs/`).
- Loading branch information
1 parent
5325f03
commit 73636ca
Showing
9 changed files
with
1,160 additions
and
1,132 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
Convert the remaining Admin API documentation files to markdown. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
# Account validity API | ||
|
||
This API allows a server administrator to manage the validity of an account. To | ||
use it, you must enable the account validity feature (under | ||
`account_validity`) in Synapse's configuration. | ||
|
||
## Renew account | ||
|
||
This API extends the validity of an account by as much time as configured in the | ||
`period` parameter from the `account_validity` configuration. | ||
|
||
The API is: | ||
|
||
``` | ||
POST /_synapse/admin/v1/account_validity/validity | ||
``` | ||
|
||
with the following body: | ||
|
||
```json | ||
{ | ||
"user_id": "<user ID for the account to renew>", | ||
"expiration_ts": 0, | ||
"enable_renewal_emails": true | ||
} | ||
``` | ||
|
||
|
||
`expiration_ts` is an optional parameter and overrides the expiration date, | ||
which otherwise defaults to now + validity period. | ||
|
||
`enable_renewal_emails` is also an optional parameter and enables/disables | ||
sending renewal emails to the user. Defaults to true. | ||
|
||
The API returns with the new expiration date for this account, as a timestamp in | ||
milliseconds since epoch: | ||
|
||
```json | ||
{ | ||
"expiration_ts": 0 | ||
} | ||
``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
# Shared-Secret Registration | ||
|
||
This API allows for the creation of users in an administrative and | ||
non-interactive way. This is generally used for bootstrapping a Synapse | ||
instance with administrator accounts. | ||
|
||
To authenticate yourself to the server, you will need both the shared secret | ||
(`registration_shared_secret` in the homeserver configuration), and a | ||
one-time nonce. If the registration shared secret is not configured, this API | ||
is not enabled. | ||
|
||
To fetch the nonce, you need to request one from the API: | ||
|
||
``` | ||
> GET /_synapse/admin/v1/register | ||
< {"nonce": "thisisanonce"} | ||
``` | ||
|
||
Once you have the nonce, you can make a `POST` to the same URL with a JSON | ||
body containing the nonce, username, password, whether they are an admin | ||
(optional, False by default), and a HMAC digest of the content. Also you can | ||
set the displayname (optional, `username` by default). | ||
|
||
As an example: | ||
|
||
``` | ||
> POST /_synapse/admin/v1/register | ||
> { | ||
"nonce": "thisisanonce", | ||
"username": "pepper_roni", | ||
"displayname": "Pepper Roni", | ||
"password": "pizza", | ||
"admin": true, | ||
"mac": "mac_digest_here" | ||
} | ||
< { | ||
"access_token": "token_here", | ||
"user_id": "@pepper_roni:localhost", | ||
"home_server": "test", | ||
"device_id": "device_id_here" | ||
} | ||
``` | ||
|
||
The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being | ||
the shared secret and the content being the nonce, user, password, either the | ||
string "admin" or "notadmin", and optionally the user_type | ||
each separated by NULs. For an example of generation in Python: | ||
|
||
```python | ||
import hmac, hashlib | ||
|
||
def generate_mac(nonce, user, password, admin=False, user_type=None): | ||
|
||
mac = hmac.new( | ||
key=shared_secret, | ||
digestmod=hashlib.sha1, | ||
) | ||
|
||
mac.update(nonce.encode('utf8')) | ||
mac.update(b"\x00") | ||
mac.update(user.encode('utf8')) | ||
mac.update(b"\x00") | ||
mac.update(password.encode('utf8')) | ||
mac.update(b"\x00") | ||
mac.update(b"admin" if admin else b"notadmin") | ||
if user_type: | ||
mac.update(b"\x00") | ||
mac.update(user_type.encode('utf8')) | ||
|
||
return mac.hexdigest() | ||
``` |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.