Authentication

Ainua Portal uses OAuth v2.0 to authenticate to Ainua Portal REST API’s.

It is recommended to create a dedicated connector for each data source (back-office solution). By creating a dedicated connector, one can conveniently update users and items within the same scope without needing to worry about using master identities over all data sources. See more about combining identities under Users API.

Authenticating via OAuth requires the following steps:

1. Create a connector
   • Using Ainua Portal admin
   • Get ainua_url, client_id and client_secret
2. Request a token
   • Using ainua_url, client_id and client_secret
   • Get bearer_token
3. Make authenticated requests
   • Using bearer_token

Create a connector

First create a connector in the Ainua Portal administration. To do this, you must be an admin of your Ainua Portal tenant. This is a one-time operation per back-office integration. You will be provided with a ainua_url, client_id and a client_secret. Please note this information down, as it will be required for the next step.

Request a token

After creating a connector, next thing is to obtain a bearer token. This operation requires the following parameters:

• ainua_url - the ainua url displayed when you created connector in the previous step
• client_id - the client id displayed when you created connector in the previous step
• client_secret - the client secret displayed when you created connector in the previous step
• grant_type - must be set to client_credentials

Request

POST `https://{ainua_url}/realms/ncp/protocol/openid-connect/token`

Header

Content-type: application/x-www-form-urlencoded

Body

grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}

Response will contain the bearer_token to be used in following requests.

Note

The client_id and client_secret mentioned above were displayed when the connector was created in the prior step. The token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call request token again to generate a new one.

Make authenticated requests

To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:

Authentication: Bearer {bearer_token}