Optional Implementation - API Development

Legacy Rewards & Recognition API Development

There are two versions of the Legacy Rewards & Recognition API offered: Version 2 and Version 3. We advise using Version 3 endpoints over Version 2 endpoints whenever possible. All requests must be made over HTTPS.

Please contact your account manager for API enablement and an OAuth 2.0 client_id and client_secret. A redirect_uri for OAuth 2.0 must be provided to your account manager and must begin with https://.

API Host

All API requests will include a host. The host will vary for all customers and depends on the environment and subdomain.

API Authentication

All requests to API endpoints will use a bearer token retrieved using the OAuth 2.0 Authorization Code Grant protocol. The bearer token will be limited in authorization scope by the permissions of the authenticated user completing the authorization request. Follow the steps below to retrieve a bearer token.

Step 1: Authorization Request

Open a web browser of your choice and log in to your KazooHR environment.

In the browser where you have successfully authenticated, make a GET request to your Authorization URL. This url will be different for each customer, depending on three variables.

Authorization URL: https://{host}/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code

• host - see API Host section above
  • For Example: a customer with the subdomain “example” that is connecting to the production environment will use the host example.youearnedit.com
• client_id - this value is provided by your KazooHR account manager
  • For Example: the client id will be be a string such as f0cdc5035bb3f41e271315546817fd7941fbeb69307330fefd222c3c5f513556
• redirect_uri - this value is provided by the customer to the KazooHR account manager; this is where the authorization_code will be delivered
  • For Example: a customer may have provided a value such as https://example.com/auth/callback

After making the request to your Authorization URL, you will be prompted to “Authorize your account for use with YouEarnedIt?”. Click “Authorize” to continue.

After clicking “Authorize”, a GET request will be made to your redirect_uri. This request will contain an authorization_code in the query string: ?code={authorization_code}. This authorization_code will be necessary for the next step.

Step 2: Token Request

Using an API client such as Postman, make a POST request to your Token URL. This url will be different for each customer, depending on five variables.

Token URL: https://{host}/oauth/token?grant_type=authorization_code&scope=API&code={code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}

• host - see API Host section above
• code - this value is provided in the query string of a GET request to your redirect_uri; this request is made in response to your authorization request
• client_id - this value is provided by your KazooHR account manager
• client_secret - this value is provided by your KazooHR account manager
• redirect_uri - this value is provided by the customer to the KazooHR account manager; this is where the authorization_code was delivered

Sample Response Payload:

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 1209600,
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": 1627944485
}

You have now successfully retrieved an access_token that you may use as a bearer token for requests to the Version 2 and Version 3 endpoints detailed in the API Endpoints section below.

The access_token expires in 2 weeks. To retrieve a new access_token, repeat the API Authentication steps 1 and 2 or make a refresh token request.

Step 3: Refresh Token Request

Using an API client such as Postman, make a POST request to your Refresh Token URL. This url will be different for each customer, depending on two variables.

Refresh Token URL: https://{host}/oauth/token?grant_type=refresh_token&refresh_token={refresh_token}

• host - see API Host section above
• refresh_token - this value is provided in the response payload of the Token URL request

Sample Response Payload:

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 1209600,
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": 1627944485
}

API Endpoints

Both the Version 2 and Version 3 API offer a variety of endpoints at two different base URLs. The host depends on the environment and subdomain (see API Host section above). Each version’s documentation provides a comprehensive list of endpoints offered.

Headers

All requests to API endpoints must include these headers:
Accept: application/json
Content-Type: application/json
Authorization: Bearer {access_token}

HTTP Status Codes

Paged Responses

Some responses (where indicated in the endpoints documentation) are paged. Such responses will be wrapped with paging information, along with a “data” property containing the requested data:

{
  "page": 1,
  "page_size": 25,
  "page_count": 6,
  "count": 150,
  "data": [...]
}

API development and testing recommendation

We recommend that you complete all API testing with a demo environment before connecting to production.

External Resources

• Documentation: OAuth 2.0 Authorization Code Grant
• Video: OAuth 2.0: An Overview