Authentication and Authorization

You can authenticate and authorize using the OPA 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 Deploy Admin role for each collection they need to access.

For calls to Batch Assess REST API, create an API client and give it the Determinations API role (unless Determinations API has been configured to allow anonymous access).

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 currently supported.

For Hub REST API, use 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/auth?grant_type=client_credentials&client_id={api-client-id}&client_secret={api-client-secret}

For Batch Assess REST API, use the following URI to obtain the OAuth2 access tokens:

https://{your_site_interface}/determinations-server/batch/auth?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 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 the form: Authorization=Bearer {access-token}

To access Batch Assess 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.