A Brief Guide to the Achievers Open API

July 3, 2018 Stefan Kramreither

The Achievers Open API is an initiative to help you integrate our Employee Engagement Platform into your company’s workflow with the tools that your company already uses. This basic guide will help you fully utilize our rewards, recognition, and employee engagement features.

You can use the Open API with any existing workplace system, such as social collaboration, performance management, talent acquisition, or learning tools. Our goal is to make it as easy as possible for you to put the features that we provide in the most convenient place for you.

This post will go over the following techniques to make it easier to get started with the Open API:

  • Authorization
  • Paging
  • Documentation

Authorization

OAuth 2.0 is the industry-standard authorization protocol, allowing different actions to be performed based on authorization method. Achievers supports two methods:

  1. Client credentials flow for when you want to access endpoints that do not require user authentication. For example, retrieving a list of members in a program.
  2. Authorization code flow for when you do need user authentication. For example, sending someone a recognition.

Before working with either flow, make sure to get the client_id and client_secret from your program administrator. These values are like your username and password for accessing Achievers, so make sure to keep them secret.

You will also need to know the scope of your application. This is a space-separated list of permissions that you need to use our API endpoints. We provide:

  • read which can only read data, such as a list of users.
  • write which can only write data, such as sending a recognition.
  • read write which can read and write data.

Client Credentials Flow

This flow only involves one step, making a POST request to /oauth/v2/openIDConnectClient/token with the following JSON body:

{
"grant_type": "client_credentials",
"scope": "<scopes>",
"client_id": "<client_id>",
"client_secret": "<client_secret>"
}

Replace <client_id> and <client_secret> with the values from your program administrator and <scopes> with the list of permissions you need. The response will look like:

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

The <access_token> allows you to perform API requests by setting the Authorization HTTP header to Bearer <access_token>.

Authorization Code Flow

Before using this method, confirm with your program administrator that a callback URL is set with your OAuth configuration. You must set up this URL so that it is accessible from the internet. This flow involves two steps and is a little more complex than the previous example.

First, send a GET request to:

/oauth/v2/openIDConnectClient/authorize?response_type=code&client_id=<client_id>&scope=<scopes>&state=XYZ

Replacing <client_id> and <scopes> appropriately. If the user is not logged in, it will redirect you to the program login page. After this, they will be redirected to a page with a dialog box asking for permission. This only occurs once, after which, the user will finally be redirected to the callback URL with the following query string:

https://<callback_url>?code=<authorization_code>

Make sure that your callback URL is set up correctly as it will need to capture the <authorization_code>which will be used in the next step.

Second, send a POST request to /oauth/v2/openIDConnectClient/token with the following JSON body:

{
"grant_type": "authorization_code",
"code": "<authorization_code>",
"client_id": "<client_id>",
"client_secret" "<client_secret>"
}

Replace <authorization_code> with the value given in the callback URL from the previous step. Also, set <client_id> and <client_secret> like before. The response should look like:

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

Where <access_token> functions as described in Client Credentials Flow.

Paging

When querying collection API endpoints, paging is available in a standardized manner. Here is an example of the JSON response:

{
"paging": {
"totalItems": 25,
"totalPages": 5,
"page": 2,
"pageSize": 5,
"self": "example.achievers.com/endpoint?page=2&pageSize=5",
"first": "example.achievers.com/endpoint?page=1&pageSize=5",
"previous": "example.achievers.com/endpoint?page=1&pageSize=5",
"next": "example.achievers.com/endpoint?page=3&pageSize=5",
"last": "example.achievers.com/endpoint?page=5&pageSize=5"
},
items: [...]
}

The paging object contains information about the page you are on, the page size, and links to the first, previous, current, next, and last pages. The items array contains the multiple objects that are returned. For example, if querying the users endpoint, the multiple objects returned would be a list of users.

Documentation

Lastly, we have improved documentation about what endpoints exist and how to use them. We’ve set documentation standards across our platform for increased maintainability and re-usability. In addition, every time we release a new endpoint, the documentation is updated automatically so that keeping up-to-date is a seamless process. Click here to view a list of our endpoints and here for the developer portal which is home to our official API documentation.

By following this guide, you can take full advantage of our Employee Engagement Platform. With proper standardization across documentation, authentication, and usage, your vision will be straightforward to implement. These improvements make working with Achievers to build your custom integration easier than ever!


A Brief Guide to the Achievers Open API was originally published in Achievers Tech on Medium, where people are continuing the conversation by highlighting and responding to this story.

Previous Article
Promoting Culture Via Magic: The Gathering
Promoting Culture Via Magic: The Gathering

Written By: Matthew Thomason & Tanya CourtneyTanya Courtney & Aris Zakinthinos playing Magic: The Gathering...

Next Article
Conquering Imposter Syndrome
Conquering Imposter Syndrome

Have you ever felt like you’re playing pretend? Like everyone except you knows what they’re talking about a...