Table of Contents
The UKG API employs the OAuth 2.0 standard for authentication. Each API request must include an HTTP Authorization header containing an OAuth 2.0 access token. It is crucial to note that requests must be authenticated and made over HTTPS; otherwise, the request will fail.
Prerequisites:
To generate tokens, the following prerequisites are necessary:
Headers:
– Content-Type: application/x-www-form-urlencoded
– appkey: APP_KEY
Note: Obtain the APP_KEY from an employee with the appropriate Developer Admin permissions. For more information, refer to the “Generate and Access App Keys” topic.
AI Platform
UKG Technology Partner
Custom UKG solutions, built around exactly what you need.
Log In and Generate Tokens:
To log in to the system and obtain an access token and a refresh token, perform a POST call to the authentication URL:
https://HOSTNAME/api/authentication/access_token
Include the following in the request body:
– username: USERNAME
AI Platform
UKG Technology Partner
Need something UKG doesn't do out of the box? We build it.
– password: PASSWORD
– client_id: CLIENT ID
– client_secret: CLIENT PASSWORD
– grant_type: password
– auth_chain: OAuthLdapService
Include the following HTTP headers:
– Content-Type: application/x-www-form-urlencoded
– appkey: APP_KEY
A successful call returns:
– access_token: A string representing the access token.
– refresh_token: A string used to obtain a new access token when the current access token becomes invalid or expires.
– scope: Informs the client of the scope of the issued access_token.
– token_type: Defines the type of token profile issued by the server, such as Bearer.
– expires_in: Lifetime in seconds of the access_token.
Refresh a Token:
To use a refresh token to generate a new access token, perform a POST call to the authentication URL:
https://HOSTNAME/api/authentication/access_token
Include the following HTTP headers:
– Content-Type: application/x-www-form-urlencoded
– appkey: APP_KEY
Include the following in the request body:
– refresh_token: REFRESH_TOKEN
– client_id: CLIENT ID
– client_secret: CLIENT PASSWORD
– grant_type: refresh_token
– auth_chain: OAuthLdapService
A successful call returns:
– access_token: A string representing the new access token.
– scope: Informs the client of the scope of the issued access_token.
– token_type: Defines the type of token profile issued by the server.
– expires_in: Lifetime in seconds of the new access_token.
Revoke a Token:
To revoke both access and refresh tokens, perform a POST call to the authentication URL:
https://HOSTNAME/api/authentication/token/revoke
Include the following HTTP headers:
– Content-Type: application/x-www-form-urlencoded
– appkey: APP_KEY
Include the following in the request body:
– token: ACCESS_OR_REFRESH_TOKEN
– client_id: CLIENT ID
– client_secret: CLIENT PASSWORD
A successful call returns an HTTP 200 status code.
Code Examples:
Generate Tokens:
cURL:
bash
curl -X POST \
https://HOSTNAME/api/authentication/access_token \
-H 'appkey: APP_KEY' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'username=USERNAME&password=PASSWORD&client_id=CLIENT ID&client_secret=CLIENT PASSWORD&grant_type=password&auth_chain=OAuthLdapService'
Java OkHttp:
java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "username=USERNAME&password=PASSWORD&client_id=CLIENT ID&client_secret=CLIENT PASSWORD&grant_type=password&auth_chain=OAuthLdapService");
Request request = new Request.Builder()
.url("https://HOSTNAME/api/authentication/access_token")
.post(body)
.addHeader("content-type", "application/x-www-form-urlencoded")
.addHeader("appkey", "APP_KEY")
.build();
Response response = client.newCall(request).execute();
This call returns a response body containing the access_token and refresh_token.
Refresh a Token:
cURL:
bash
curl -X POST \
https://HOSTNAME/api/authentication/access_token \
-H 'appkey: APP_KEY' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'refresh_token=REFRESH_TOKEN&client_id=CLIENT ID&client_secret=CLIENT PASSWORD&grant_type=refresh_token&auth_chain=OAuthLdapService'
Java OkHttp:
java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "refresh_token=REFRESH_TOKEN&client_id=CLIENT ID&client_secret=CLIENT PASSWORD&grant_type=refresh_token&auth_chain=OAuthLdapService");
Request request = new Request.Builder()
.url("https://HOSTNAME/api/authentication/access_token")
.post(body)
.addHeader("content-type", "application/x-www-form-urlencoded")
.addHeader("appkey", "APP_KEY")
.build();
Response response = client.newCall(request).execute();
This call returns a response body containing the new access_token.
Revoke a Token:
cURL:
bash
curl -X POST \
https://HOSTNAME/api/authentication/token/revoke \
-H 'appkey: APP_KEY' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'token=ACCESS_OR_REFRESH_TOKEN&client_id=CLIENT ID&client_secret=CLIENT PASSWORD'
Java OkHttp:
java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "token=ACCESS_OR_REFRESH_TOKEN&client_id=CLIENT ID&client_secret=CLIENT PASSWORD");
Request request = new Request.Builder()
.url("https://HOSTNAME/api/authentication/token/revoke")
.post(body)
.addHeader("content-type", "application/x-www-form-urlencoded")
.addHeader("appkey", "APP_KEY")
.build();
Response response = client.newCall(request).execute();
A successful call returns an HTTP 200 status code.
