OAuth Authentication Flow

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

Prerequisites

• Understand the differences between UKG HR Service Delivery environments (e.g., staging vs. production) to isolate tests from live data.
• Ensure you're testing in a safe, non-live environment.
• Request the following from the IPM team:
  • $APPLICATION_ID
  • $APPLICATION_SECRET
  • $CLIENT_ID
• Familiarity with cURL is recommended for using the terminal. (More on cURL at Everything cURL) :contentReference[oaicite:1]{index=1}

Flow to Gain Access to UKG HR Service Delivery APIs

Using cURL and a Terminal

In examples, the API URL is abstracted as $ENV_URL, and credentials appear as placeholders: $APPLICATION_ID, $APPLICATION_SECRET, and $CLIENT_ID. :contentReference[oaicite:2]{index=2}

1. Request Your OAuth Token

Use Basic Authentication to obtain a client OAuth token:

curl -X POST -u "$APPLICATION_ID:$APPLICATION_SECRET" \
  -H "Content-Type: application/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"

2. Check the OAuth Service’s Response

A successful (HTTP 200) response payload looks like:

{
  "token_type": "bearer",
  "access_token": "$OAUTH_TOKEN",
  "expires_in": 8640000
}

3. Save Your Token for Future Calls

From the 200 response, you'll receive:

• token_type: Always "bearer", per OAuth 2.0 standards—use this in Authorization headers.
• access_token: Your token to authenticate future API calls—store it securely.
• expires_in: The token's lifetime in seconds, preconfigured on UKG’s side.

Hint: Implement logic to renew the token before it expires to avoid disruptions.

4. Start Calling UKG HR Service Delivery APIs

Include the access token in the Authorization header:

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

5. Renew Your Token When Needed

If your token is close to expiring—or already expired—simply repeat the "Request Your OAuth Token" step to get a new one.

6. Revoke a Token

To proactively revoke a token (e.g., after a task completes), post it with your credentials: