🔒 Authentication

Most of the API endpoints require authentication to function. We rely on a self-hosted instance of Keycloak as the IdP of the entire platform. Users are registered both on Keycloak and our database, keeping them in sync.

We support all the authentication methods provided by Keycloak itself. Please refer to this page for a very in-depth guide of all the possible authorization flows.

🔑🧑🏻 Authenticating with password

This method should be used EXCLUSIVELY for machine-to-machine interaction. Because the password of an account is involved, it is not possible to use it on a client, only on a trusted server (otherwise the password would be exposed to everyone!). Please remember to never log the password anywhere and keep it secure (possibly in encrypted environment variables).

This method allows a server to obtain a token of a specific account and call APIs authenticated as them. The token expires after a specific amount of time. Refer to this page for more details.

The following is an example API call to authenticate with client credentials:

curl --location --request POST 'https://iam.staging.gayadeed.it/auth/realms/gaya/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>' \
--data-urlencode 'username=<EMAIL>' \
--data-urlencode 'password=<PASSWORD>' \
--data-urlencode 'scope=openid profile email' \
--data-urlencode 'grant_type=password'

The fields CLIENT_ID and CLIENT_SECRET will be communicated separately.

The fields EMAIL and PASSWORD are the credentials of the user you want to get a token for.

The response will look like this:

{
    "access_token": "ey...",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "refresh_token": "ey...",
    "token_type": "Bearer",
    "id_token": "ey...",
    "not-before-policy": 0,
    "session_state": "<uuid>",
    "scope": "openid email profile"
}

Store access_token and pass it in the Authorization header of every authenticated call in the format: Bearer <access_token>