Authentication and Security for UKG PRO WFM (Dimensions) API

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.

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

– 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.