Call the API from a server
Get an app-only token for an API client and make a first request to the user directory from a server or a script.
An app-only token has no user identity. To read the account data of a user or to act as a user, use a Login client instead.
Prerequisites
- Bash with
curlandjq. - An approved API client with
remilia:directory.read. For the steps, see Register an application.
Warning: Keep shell tracing disabled while you use the credentials. set -x
and curl -v can print them.
Steps
-
Export your client ID:
export REMILIA_CLIENT_ID="your-client-id" -
Read your client secret into the shell without echo:
read -rs REMILIA_CLIENT_SECRET # paste the secret export REMILIA_CLIENT_SECRET -
Request an access token with the
client_credentialsgrant:ACCESS_TOKEN=$(curl --fail-with-body -sS \ https://www.remilia.net/oidc/realms/remilia/protocol/openid-connect/token \ -d grant_type=client_credentials \ -d client_id="$REMILIA_CLIENT_ID" \ --data-urlencode "client_secret=$REMILIA_CLIENT_SECRET" \ | jq -er '.access_token') -
Request the first page of the user directory:
curl --fail-with-body -sS \ 'https://www.remilia.net/api/v1/users?limit=1' \ -H "Authorization: Bearer $ACCESS_TOKEN"
Result
The token response holds access_token and expires_in, the lifetime of the
token in seconds:
{
"access_token": "eyJhbGciOi...",
"expires_in": 900
}The directory response wraps the page in data, with users and next_cursor.
An empty page is a valid response. For a response example and the pagination
rules, see Enumerate the user directory.
Your script reuses the access token until it nears expiry. It then requests another token with the same credentials. Client Credentials returns no refresh token.
Troubleshooting
- If the token request returns
invalid_client, the application is not approved, or the ID and the secret do not match. - If the request returns
403 insufficient_scope, the token lacksremilia:directory.read.
For every error code, see Errors.
Next steps
An API client can also read global chat with remilia:chat.read. For the
features of each client, see
What you can build.
