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

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 \
  -d client_id=79403d86-8451-41fd-9da8-e06fe422222a \
  -d client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
  -d grant_type=authorization_code \
  -d code=IPstdyFE2vWC6Jb2wODGJPe0fcoNYq \
  -d 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.

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

Implicit

The implicit grant is used when the client secret confidentiality is not guaranteed. This is typical of web applications (i.e. applications that run in a web browser).

Your application must send the user to the /oauth/authorize URL with these parameters:

response_type=token
client_id=79403d86-8451-41fd-9da8-e06fe422222a

After the user authorizes the application he will be redirected to the configured redirect URI with the following parameters:

access_token=kp-oauth2-PNbeKKEIljvc1V7IL5zzK5GiFgbBs6
token_type=Bearer
expires_in=3600
scope=apiv1

As the access token is directly given to the user-agent to forward to the application it may be exposed to the user and other applications on the user's device. It also does not authenticate the identity of the application. Note that this type of grant does not support refresh tokens.

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 \
  -d client_id=79403d86-8451-41fd-9da8-e06fe422222a \
  -d client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
  -d grant_type=password \
  -d username=api \
  -d password=ItVaK0H.eh]o \
  https://mycompany.elium.com/oauth/token

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

{
	"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 \
 -d client_id=79403d86-8451-41fd-9da8-e06fe422222a \
 -d client_secret=10db66ea-03ab-4a5b-b1fe-61ff3c82b530 \
 -d grant_type=refresh_token \
 -d refresh_token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq \
 https://mycompany.elium.com/oauth/token

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

{
	"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 \
 -d token=kp-oauth2-GolmKhyvIQVvBFAVUHKgZ0V1Oo3yTq \
 https://mycompany.elium.com/oauth/token

Both tokens will be immediately revoked.