Authentication

Principles

Our API uses OpenID Connect (OIDC) to identify and authenticate clients.

Any request to the API is verified thus must include a valid JWT (Json Web Token).

This must be sent in the Authorization header (see examples below).

If the Authorization header is not completed and valid, the request will be considered as not authenticated (HTTP code 401).

If any alteration of the token happens (IP address change is one of them) you'll receive HTTP code 403.

More information on OpenID Connect and JWT on:

https://openid.net/connect/
https://jwt.io/

Credentials

Your AOS credentials can be used to communicate with API if the Saqara team gave you the access.

Please contact us if it is not the case.

Permissions

To access our APIs, the logged-in user must have Administrator rights on the organization(s) called by the API.

If your user does not have these permissions, you will receive a HTTP 403 Forbidden exception.

Also, to access the APIs, you need to request activation of the API for your or your organization(s).

Obtain a JSON Web Token

To get a JWT token you need to do a POST type request with user and password and some additional parameters to the authentication server on the following URLs:
• Staging: https://account.staging.saqara.com/auth/realms/AOS-dev/protocol/openid-connect/token
• Production: https://account.go-aos.io/auth/realms/AOS-prod/protocol/openid-connect/token

The request must be sent as "Form":

Parameter Optional Default Value Description
client_id false Staging : aos-client-app
Production: aos-api-access		 The value of the client_id is not the same between staging and production environment. Please make sure you set the correct client_id based on your current environment.
grant_type false password It allows our authentication portal to know the type of login you want to use. By default it is "password".
username false The username of your account on AOS.
password false The password of your account on AOS.

Request example (Staging)

POST https://account.staging.saqara/auth/realms/AOS-dev/protocol/openid-connect/token

username=...
password=...
client_id=aos-client-app
grant_type=password

Request example (Production)

POST https://account.go-aos.io/auth/realms/AOS-prod/protocol/openid-connect/token
username=...
password=...
client_id=aos-api-access
grant_type=password

Response

Status: 200 OK
{
    "access_token": "eyJhb...",
    "expires_in": 10800,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhb...",
    "token_type": "Bearer",
    "not-before-policy": 1665000000,
    "session_state": "00000000-0000-0000-0000-000000000000",
    "scope": "email profile"
}