Authentication

The Achievers API uses the OAuth 2.0 protocol for authentication and authorization. Achievers supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

Generating and managing keys for the Achievers Open API is done by your program administrator using our self-serve API OAuth Keys tool in the Client Admin Panel (CAP). Contact your program administrator to get client_secret and client_id credentials. See the API OAuth Keys tool page for more information.

Access tokens

Before your client application can access the Achievers API, it must request an access token from Achievers. An access token can grant varying levels of access to multiple endpoints.

In order for your application to request an access token, you first need to obtain a client_id and a client_secret from your program administrator.

After your application has obtained an access token, it must include the token in an Authorization header with each HTTP request sent to the endpoint.

There are two ways to request an access token:

If you are accessing endpoints that do not require user authorization, you will go through the 1-step client_credentials flow.
If you require access to a user's account to make requests on their behalf, you will go through the 3-step, authorization_code flow.

Scopes

You need to include a list of requested scopes during the OAuth flow. When using the authorization_code flow, users will be asked to grant permission to your application for the requested scopes once they have authenticated. If you are not sure what scopes to request, refer to the documentation for that specific endpoint. If the endpoint documentation does not specify the scopes, the following scopes are available:

Scope	Description
`read`	grants permission to read data
`write`	grants permission to write data
`read,write`	grants permission to read and write data

Client Credentials flow

The tokens granted for the client_credentials flow are valid for endpoints that do not require user authorization, such as retrieving a list of users or recognitions.

Step 1: Obtain an access token

If you are accessing an endpoint that only requires the grant type client_credentials, you can get the access token directly.

First, make a request to /oauth/v2/openIDConnectClient/token and provide your client_id and client_secret as the username:password.

curl -X POST -H "Content-Type: application/json" \
-d '{"grant_type": "client_credentials", "scope": "<scopes>", "client_id": "<client_id>", "client_secret": "<client_secret>"}' \
'https://example.uat.achievers.com/oauth/v2/openIDConnectClient/token'

The response should look like the following:

{
  "access_token": <access_token>,
  "expires_in": 1512930181,
  "token_type": "Bearer",
  "scope": "read"
}

Make sure you note when your OAuth access token is going to expire, by checking the expires_in field. This field is a UNIX timestamp. If your token is within 2 hours of expiring or already has expired, you will have to make a request to get a new token. If the token is not within 2 hours of expiring and you make a request to get a new token, we will reissue the same token that you currently have.

When making requests, provide the returned access_token in the Authorization header, in the form Authorization: Bearer <access_token>. The token is valid for multiple requests, but expires after 365 days, after which you will have to request a new token.

In this example, we are querying the /api/v5/users endpoint to obtain a list of users in your program. As this endpoint does not require authorization from a user, you need a token that has a grant_type of client_credentials.

curl -k --include -X GET -H 'Authorization: Bearer <access_token>' \
https://example.uat.achievers.com/api/v5/users

Authorization Code flow (for requests on behalf of a user)

Making requests on behalf of a user is a three-part process. The user must grant your application permission to access their data and/or perform actions on their behalf. Once they have authorized your application, you will receive an authorization code that you will need to capture and then use to obtain an access token.

For this flow, a client_id and client_secret pair is still required, and a redirect URL must be provided. Please contact your program administrator to set the redirect URL for your integration and to obtain your client_id and client_secret.

Step 1: Requesting access to the user's Achievers account

First, direct the user to the following URL:

"https://example.uat.achievers.com/oauth/v2/openIDConnectClient/authorize?response_type=code&client_id=<client_id>&scope=<scopes>&state=XYZ

Set the query parameters appropriately for your application. Once the user has authenticated with Achievers, they will be presented with a list of the permissions that your application is requesting, and they will be prompted to approve or deny the request.

Step 2: Handling the redirect

Once the user has authorized your application, an authorization code is generated. A request is then made to the callback URL that has been provided, with the authorization code included in code field in the query params.

Example cURL:

curl –X GET ‘https://<yourcallbackurl>/?code=<authorization_code>

On your application side, you will handle this callback and capture the code. Once this has happened, you can use the code in your token request.

Step 3: Obtain an access token

Similar to the client_credentials method, you will make a request with your client_id and client_secret. However, this time you will also be passing the authorization code that you captured in Step 2 and the grant_type is set to authorization_code.

curl -X POST -H "Content-Type: application/json" -d\
'{"grant_type": "authorization_code", "code": "<authorization_code>", "client_id": "<client_id>", "client_secret": "<client_secret>"}'\ 
'https://example.uat.achievers.com/oauth/v2/openIDConnectClient/token'

The response should look like the following:

{
  "access_token": <access_token>,
  "expires_in": 1512930181,
  "token_type": "Bearer",
  "scope": "read"
}