Skip to content

API integration guides

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 curl and jq.
  • 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

  1. Export your client ID:

    export REMILIA_CLIENT_ID="your-client-id"
  2. Read your client secret into the shell without echo:

    read -rs REMILIA_CLIENT_SECRET   # paste the secret
    export REMILIA_CLIENT_SECRET
  3. Request an access token with the client_credentials grant:

    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')
  4. 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 lacks remilia: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.