Authentication

The Elium API uses OAuth 2.0. Every call is made on behalf of a user account. Your program gets an access token for that account and sends it with every request:

Authorization: Bearer kp-oauth2-IrZ30CY27BBG8hryQOAvWVQ1isX1Na

Before you start

Register your program as a connected app, in Settings > Advanced > Connected apps. You get a client ID and a client secret, and you declare the redirect URLs the program can send users back to. API and connected applications describes every option.

Tick the API scope. In requests, its name is apiv1, and it covers the whole API: everything the user can do in Elium, your program can do too. The two MCP scopes are for AI assistants and do not give access to the API.

An app marked Trusted skips the approval screen. Use it for a program your organisation controls, such as an internal integration, and never for one it does not.

The platform publishes its OAuth configuration at the standard address, so a library can configure itself from the platform address alone:

https://your-platform-name.elium.com/.well-known/oauth-authorization-server

Authorization code

This is the flow for an application that acts on behalf of people who sign in themselves. The user approves your application in their browser, and your application exchanges the resulting code for tokens.

Use PKCE (Proof Key for Code Exchange, RFC 7636) on this flow. Elium accepts it from every application and requires it from an application that has no client secret. Your application creates a random code_verifier, sends its SHA-256 hash as the code_challenge, and proves it holds the verifier when it asks for the token. Every OAuth library does this for you.

1. Send the user's browser to the authorisation address with these parameters:

   https://your-platform-name.elium.com/oauth/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=https://myapplication.example/oauth2
     &scope=apiv1
     &code_challenge=YOUR_CODE_CHALLENGE
     &code_challenge_method=S256
     &state=A_RANDOM_VALUE
   

   Copy code

2. The user signs in to Elium if needed and sees the approval screen. A trusted app skips it.

   Enlarge image

3. If the user accepts, Elium sends the browser back to your redirect URL with a code parameter:

   https://myapplication.example/oauth2?code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq&state=A_RANDOM_VALUE
   

   Copy code

4. From its server, your application exchanges the code for tokens:

   curl --request POST \
     --data "grant_type=authorization_code" \
     --data "client_id=YOUR_CLIENT_ID" \
     --data "client_secret=YOUR_CLIENT_SECRET" \
     --data "code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq" \
     --data "code_verifier=YOUR_CODE_VERIFIER" \
     --data "redirect_uri=https://myapplication.example/oauth2" \
     https://your-platform-name.elium.com/oauth/token
   

   Copy code

The response is a JSON document with the access token, its lifetime in seconds and a refresh token:

{
  "access_token": "kp-oauth2-IrZ30CY27BBG8hryQOAvWVQ1isX1Na",
  "token_type": "Bearer",
  "expires_in": 864000,
  "refresh_token": "kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq",
  "scope": "apiv1"
}

Password

This flow is for a script or a back-end job that runs without anyone present. The program signs in with a username and password and gets tokens directly.

Create a dedicated user account for it, with a name that says what it is for, a strong password, and no more rights than the job needs. Do not use a person's account.

curl --request POST \
  --data "grant_type=password" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "username=api-sync" \
  --data "password=THE_ACCOUNT_PASSWORD" \
  https://your-platform-name.elium.com/oauth/token

The response has the same shape as for the authorization code grant.

Renew the access token

The access token expires after the number of seconds given in expires_in. After that, the API answers with an authentication error. Ask for a new one with the refresh token:

curl --request POST \
  --data "grant_type=refresh_token" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  --data "refresh_token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq" \
  https://your-platform-name.elium.com/oauth/token

If the access token has expired or is close to expiry, you receive a new access token and a new refresh token, and the old pair stops working. Otherwise the same tokens come back with their remaining lifetime. Always store the tokens from the latest response.

{
  "access_token": "kp-oauth2-DX5GlUVeLgjD4zUaOkpXtinj7AOhZb",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "kp-oauth2-0jTuX4wknsSlkoqRcrSTRyslzqw79f",
  "scope": "apiv1"
}

Revoke a token

To revoke an access token or a refresh token, post it to the revocation address:

curl --request POST \
  --data "token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq" \
  --data "client_id=YOUR_CLIENT_ID" \
  --data "client_secret=YOUR_CLIENT_SECRET" \
  https://your-platform-name.elium.com/oauth/revoke

Revoking one token revokes the other as well.

Users can also revoke an app themselves, from Settings > Authorised apps, and a system administrator can delete the app for everyone. Both are described in API and connected applications.