Authentication in details

The Elium API uses OAuth 2.0 to enable an application to make calls on behalf of an Elium user.

Registering your application

Before using the API you must register your application in the Security tab of the administration panel. Choose a name and the URL which will handle authorization codes or access tokens.

connected apps

Note that Elium only supports a single scope for now, which covers the entire API.

Sometimes asking the permission of the user is not necessary. For instance in the case of a pre-approved corporate application. To mark an application as trusted and skip user's approval you can tick the Trusted flag in the application's parameters.

Authorization flows

Every action is made on behalf of a user account. Your application needs to obtain an access token for the chosen user account and then pass that token in the header of every request. Elium supports the following authentication flows.

Authorization code

This is most commonly used authentication flow. It is made for server-side applications which can guarantee the client secret confidentiality. The user is asked to authorize your application to access his account. An authorization code is then transmitted to your application though the user's web browser (user-agent).

To initiate the flow, your application must redirect the user-agent to the /oauth/authorize url with these parameters:

response_type=code
client_id=79403d86-8451-41fd-9da8-e06fe422222a
scope=apiv1

The user will be asked to log in if necessary and then will be shown the following dialog:

connected apps

If he accepts, the user-agent will be redirected to the configured redirect URI with a code parameter:

https://myapplication.com/oauth2?code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq

This user approval step is skipped if you ticked the Trusted flag when registering the application.

Your application can then use that code to request an access token:

curl --request POST \
  --data "client_id=79403d86-8451-41fd-9da8-e06fe422222a" \
  --data "client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530" \
  --data "grant_type=authorization_code" \
  --data "code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq" \
  --data "redirect_uri=https://myapplication.com/oauth2" \
  https://mycompany.elium.com/oauth/token

It returns a JSON formatted dictionary containing the access token and a refresh token. The refresh token is used to renew the access token in the event it expires.

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

Password

This type of grant can then prove useful for back-end operations, as no user interaction is required. It is advised to create a dedicated account for that purpose and limit his rights to what is needed only.

You can create a dedicated API account from the administration panel just like any regular user account. Choose a name that reflects the purpose of that account and give it a strong password. In the following, we assume an existing account with the following credentials:

login=api
password=ItVaK0H.eh]o

The access token is issued by the /oauth/token endpoint. You need to specify the client id and client secret parameters of you application. Example:

curl --request POST \
  --data client_id=79403d86-8451-41fd-9da8-e06fe422222a \
  --data client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
  --data grant_type=password \
  --data username=api \
  --data password=ItVaK0H.eh]o \
  https://mycompany.elium.com/oauth/token

The response is the same as with an authorization code grant type:

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

Renewing the access token

The given access token will expire (as mentioned in the expires_in key, 3600 seconds in this case). If your access token expires the service will respond with an error. You can renew your access token by calling the /oauth/token endpoint with a refresh token grant type:

curl --request POST \
 --data client_id=79403d86-8451-41fd-9da8-e06fe422222a \
 --data client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
 --data grant_type=refresh_token \
 --data refresh_token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq \
 https://mycompany.elium.com/oauth/token

It will issue a new access token and a new refresh token:

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

Revocation

To revoke an access token or refresh token you must post it the /oauth/revoke endpoint:

curl --request POST \
 --data token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq \
 --data client_id=79403d86-8451-41fd-9da8-e06fe422222a \
 --data client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
 https://mycompany.elium.com/oauth/revoke