OAuth authentication flow¶

Note

This document is a walkthrough describing how to initiate an API connection using UKG HR Service Delivery OAuth flow.
You will learn how to generate your first API token, leading to access UKG HR Service Delivery APIs.

Prerequisites
Flow to gain access to UKG HR Service Delivery APIs
Using cURL and a terminal

Prerequisites ¶

You need to understand the difference between UKG HR Service Delivery’s environments (to segregate your tests with live API integrations & data)
You need to make sure to test your API access on a safe, non-live environment.
You need to ask the IPM team for:
- an $APPLICATION_ID
- an $APPLICATION_SECRET
- a $CLIENT_ID
You should understand cURL basics if you intend to use this tool. You can read more about cURL at Everything cURL.

Flow to gain access to UKG HR Service Delivery APIs ¶

Using cURL and a terminal ¶

In this example, the API URL is replaced by $ENV_URL
Credentials are censored, and replaced by $APPLICATION_ID, $APPLICATION_SECRET and $CLIENT_ID

Request for your OAuth token ¶

Note

Endpoint documentation: Request Token.

Use your $APPLICATION_ID & $APPLICATION_SECRET with the following cURL command:

# Basic Authentication to get a valid Client OAuth Token
curl -X POST -u "$APPLICATION_ID:$APPLICATION_SECRET" \
  -H "Content-Type: a pplication/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=client_credentials&scope=client&client_id=$CLIENT_ID" \
  "$BASE_URL/api/v2/client/tokens"

# => returns JSON object containing the access_token
{
  "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI....",
  "token_type":"bearer",
  "expires_in":3600
}

Check in the OAuth service’s response if you were granted a token ¶

HTTP/1.1 200 OK [...]
{"token_type":"bearer","access_token":"$OAUTH_TOKEN","expires_in":8640000}

Save your token for future calls ¶

In the case of a 200 response, you can see in the payload 3 keys and their respective values:

“token_type”: UKG HR Service Delivery follows the OAuth 2.0 specification, and therefore generates a Bearer token. This field is just here to confirm the type of token sent by the API, and to help you specify it in any future calls to UKG HR Service Delivery APIs.
“access_token”: the actual token generated for your future API calls to UKG HR Service Delivery. Please store it and use it with all your future calls, until it expires or you have asked for a new one.
“expires_in”: expressed in seconds, this field specifies the life length of the token sent. This value is set in our data centers and cannot be overwritten.

Hint

UKG HR Service Delivery strongly advises to implement an expiration mechanism to make sure you renew (refresh) your access token before it expires, which leads to breaking your API flow.

Start calling UKG HR Service Delivery APIs using the previously saved token ¶

You were granted an access token to start using UKG HR Service Delivery APIs.

To use this token, simply include it in the Authorization header as in the following cURL example:

cURL -X GET
-H "Authorization: Bearer $ACCESS_TOKEN"
-H "Content-type: application/json"
-H "Accept: application/json"
"$ENV_URL/api/v2/client/$RESOURCES"

Where $RESOURCES is to be replaced as documented in UKG HR Service Delivery’s endpoints documentation.

Caution

UKG HR Service Delivery does not currently THROTTLE the amount of tokens granted per API consumer, but be aware WE WILL PROCEED TO TOKEN EXPIRATION in case of suspicious activity, i.e too many tokens generated for the same API consumer.

Use the token granted until expiry. These tokens grant access to your employee, company, and organizations data and processes, and therefore should be used and generated in a pragmatic way.

If your token is about to expire or expired, renew it ¶

Your API token has a defined life span, expressed in the expires_in attribute sent back in the 200 response payload. If your token is about to or has expired, you can (until expiration) or must (after expiration) request a new one. Simply go back to section Request for your OAuth token to do so.

Revoking a token ¶

Depending on your storage and security strategy, you might want to revoke a token, after a specific task for example.

Revoking a token requires you to POST the token itself, using your $APPLICATION_ID and $APPLICATION_SECRET:

cURL -X POST
-u "$APPLICATION_ID:$APPLICATION_SECRET" https://$ENV_URL/api/v2/client/revoke_token
-H 'Accept: application/json'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'token=$ACCESS_TOKEN'