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"
}
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.
Updated 6 months ago
Now that you can authenticate, try one of our common use cases: