Authentication and Authorization

You can authenticate and authorize using the Intelligent Advisor REST APIs by performing the following tasks.

Step 1. Create an API client user with REST API permissions

For calls to Hub REST API, create an API client. For user administration, give the API client the Hub Administrator role. For deployment administration, give the API client the Manager role for each collection they need to access.

For calls to Batch Assess REST API or Decision Service REST API, create an API client and give it the Assessment APIs role.

For more information on creating API clients, see Create an account for application integration.

Step 2. Authenticate an API client user to get an OAuth 2.0 token

API clients must access the REST API using OAuth2 tokens. Basic authentication is not supported.

For all REST APIs, POST to the following URI to obtain an OAuth2 access token, using the API client identifier and client secret created in Step 1:

https://{your_site_interface}/opa-hub/api/{version}/auth

It is recommended that you use the version with the highest version number. All the versions that are available are shown at:

https://{your_site_interface}/opa-hub/api/

For example:

https://{your_site_interface}/opa-hub/api/12.2.35/auth

The POST parameters should look something like:

grant_type:client_credentials
client_id:{api-client-id}
client_secret:{api-client-secret}

Note that requests must be sent using HTTP POST, not GET.

If authentication is successful, the response body will include an access token, to use for future API calls.

After 30 minutes of inactivity, an access token expires, and a new token must be obtained. For interactions longer than 30 mins, API clients can use a refresh token to request a new access token and continue access without needing to resend the client_id and client_secret. For more information on this flow, see Refresh an API access token

For more information on OAuth2 authorization, see The OAuth 2.0 Authorization Framework and The OAuth 2.0 Authorization Framework: Bearer Token Usage.

Step 3. Access a REST API with authorization

To access Hub REST API with an API client, use an Authorization header containing the Bearer token obtained in Step 2. The Authorization header will be in this form:

Authorization=Bearer {access-token}

To access Batch Assess REST API or Decision Service REST API with an API client, use an Authorization header containing the Bearer token obtained in Step 2. If Determinations API has been configured to allow anonymous access, no Authorization header is needed. If Determinations API has not been configured for anonymous access, anonymous requests are refused.