Skip to main content

UKG

  • Updated

This document outlines the steps required to establish a secure connection between Wisq and your UKG environment.

CONTENTS

  1. Supported Authentication Methods
  2. Identify Your UKG API Product
  3. Create a Service Account (UKG Pro)
  4. Configure Service Account Permissions
  5. Locate Your API Keys
  6. Choose and Configure Your Authentication Method
  7. Provide Credentials to Wisq
  8. Final Checklist

1. Supported Authentication Methods

Wisq supports two authentication methods for connecting to UKG. The method used depends on which UKG API product your environment uses.

Most organizations integrate with Wisq using UKG Pro REST APIs and Basic Authentication (Option A).

Only use OAuth 2.0 (Option B) if your UKG administrator has specifically provided UKG Pro Platform API credentials.

Option A — Basic Authentication with API Keys (UKG Pro)

  • Uses a dedicated Service Account with a username, password, Customer API Key, and User API Key
  • Credentials are sent with each API request via HTTP headers
  • Applies to UKG Pro core REST APIs (employee data, compensation, job history, etc.)

Option B — OAuth 2.0 Client Credentials (UKG Pro Platform)

  • Uses enterprise-grade, token-based authentication with no user interaction required after initial setup
  • Authenticated via a registered application with a Client ID and Client Secret
  • Wisq exchanges these credentials for short-lived Bearer Tokens automatically — no ongoing action required after setup
  • The OAuth 2.0 client_credentials grant type is used

Start with Section 2 to identify which UKG API Product your environment uses. Then follow the path for your authentication method:

  • Option A (Basic Auth): Complete Sections 3–5, then Section 6A, then Section 7.
  • Option B (OAuth 2.0): Skip to Section 6B, then Section 7.

If you are unsure which method to use, consult your Wisq Agent Strategist contact.

2. Identify Your UKG API Product

UKG offers several API products. The authentication method and setup steps differ depending on which UKG API product your environment uses.

UKG Product Authentication Method OAuth 2.0 Grant Type
UKG Pro (core REST APIs) Basic Auth + API Keys N/A
UKG Pro Platform OAuth 2.0 client_credentials

Most customers integrate using UKG Pro REST APIs (Option A). OAuth 2.0 is typically used only when the UKG Pro Platform APIs are required.

Note: UKG Pro WFM (Dimensions) uses the password grant type (Resource Owner Password Credentials), and UKG HR Service Delivery uses its own client_credentials variant. These products are outside the standard Wisq integration scope. If your organization requires connectivity to either, contact Wisq to discuss options.

3. Create a Service Account

A Service Account is a dedicated service account used for API integrations in UKG Pro. We strongly recommend using a dedicated service account rather than a personal admin account.

  1. Log in to UKG Pro as a System Administrator.
  2. Navigate to Menu > System Configuration > Security > Service Account Administration.
  3. Click + Add in the upper-right corner to create a new service account.
  4. Enter a descriptive username (e.g., Wisq_Service) and the email address of the responsible administrator.
  5. Click Save. After saving the service account, UKG will generate a password and display it once. Copy and save this password immediately — it cannot be retrieved later.
  6. Record the username for use in Section 6A.

If your organization requires periodic credential rotation, please notify Wisq before rotating so the connection can be updated without downtime.

4. Configure Service Account Permissions

The Service Account must be granted the specific permissions needed for the integration to function. UKG follows a least-privilege model — only enable the services and methods Wisq requires.

  1. From the Service Account Administration page, locate and open the service account you created in Section 3.
  2. Scroll to the Web Service permissions section.
  3. Enable the required services and access methods (View and/or Edit). At minimum, enable View access for the following:
    • Employee Person Details (required for all UKG API connections)
    • Any additional services within the agreed integration scope (e.g., Employee Job, Employee Compensation Details, Employee Job History Details)
  4. Save your changes.

We recommend least-privilege access aligned to the integration requirements. Contact your UKG administrator if you need assistance identifying the correct service permissions.

Note: The legacy "Personnel Integration" permission has been separated into individual permissions: Employee Person Details, Employee Compensation Details, Employee Job History Details, and Global Employee Direct Deposit. Enable only the specific permissions that are needed.

5. Locate Your UKG API Keys

UKG Pro uses two API keys for authentication. Both are found in the Service Account Administration console.

Customer API Key

  1. Navigate to Menu > System Configuration > Security > Service Account Administration.
  2. The Customer API Key is displayed at the top of the page, above the list of service accounts. This key is shared across all service accounts in your UKG tenant.
  3. Copy and record the Customer API Key.

User API Key

  1. On the same Service Account Administration page, locate the service account you created in Section 3.
  2. Each service account is assigned a unique User API Key. This key is displayed on the account detail or in the account listing.
  3. Copy and record the User API Key.

Both keys are required for API authentication. The Customer API Key identifies your UKG tenant, while the User API Key identifies the specific service account.

6. Choose and Configure Your Authentication Method

Complete the section below that matches your chosen authentication method. If you are unsure which method to use, consult your Wisq Agent Strategist contact.

Option A — Basic Authentication with API Keys

No additional UKG configuration is required beyond the Service Account, permissions, and API keys you set up in Sections 3–5.

Confirm the API Base URL

UKG Pro REST API endpoints follow this general format:

https://<host>/services/<api>/<version>/<resource>
Component Description Example
Host Your UKG data center hostname service4.ultipro.com
Resource The API service and resource path personnel/v1/employees

The hostname varies by customer data center and environment (production vs. test). Common patterns include:

<https://service><N>.ultipro.com
<https://rental><N>.ultipro.com   (sandbox/test environments)

To find your base URL: Important: Do not use the UKG login URL (for example, login.ultipro.com). API requests must use the UKG service hostname such as service#.ultipro.com.

  1. Contact your UKG administrator or consult your UKG Pro environment details.
  2. Your Wisq Agent Strategist contact will confirm which specific endpoints are required.

Required Authentication Headers

Each API request to UKG Pro requires the following headers:

Header Value
Authorization Basic <base64(username:password)>
US-Customer-Api-Key Your Customer API Key
US-User-Api-Key Your User API Key
Content-Type application/json

Credentials Summary — Basic Authentication

Wisq Connection Field What to Provide
Connection Name A friendly identifier (e.g., "Acme Corp – UKG Pro")
API Base URL Your UKG Pro REST API hostname (see above)
Username The Service Account username
Password The Service Account password
Customer API Key Found in Service Account Administration (Section 5)
User API Key Found in Service Account Administration (Section 5)

Proceed to Section 7 to transmit these credentials securely to Wisq.

Option B — OAuth 2.0 Client Credentials (UKG Pro Platform)

Step 1 — Obtain Integration Credentials

Register a new application in the UKG Developer Hub for the Wisq integration, or locate an existing application if one has already been created.

  1. Register a new application or locate the existing integration credentials for Wisq.
  2. Record the following values:
    • Client ID
    • Client Secret
  3. Note the Token Endpoint URL (Generate Token URL). This is the URL Wisq will call to exchange credentials for a Bearer Token.
  4. Note the Organization value (also referred to as the tenant identifier), which is passed as the global-tenant-id header in API requests.

The Client Secret is sensitive. Copy and save it securely at the time of creation — it may not be retrievable later.

Step 2 — Confirm the Token Endpoint and Audience

Wisq authenticates using the OAuth 2.0 client_credentials grant type. The token request uses the following parameters:

Parameter Value
grant_type client_credentials
client_id Your registered Client ID
client_secret Your registered Client Secret
audience The API audience value provided with your integration credentials

The token endpoint URL will be provided by your UKG administrator. For US-based instances, the typical endpoint is:

<https://welcome-us.ukg.net/oauth/token>

The hostname varies by region and environment.

Step 3 — Confirm the API Base URL

UKG Pro Platform API requests require the Bearer Token in the Authorization header and the organization identifier in the global-tenant-id header.

Record your API base URL. Your Wisq Agent Strategist contact will confirm which specific endpoints are required.

Credentials Summary — OAuth 2.0

Wisq Connection Field What to Provide
Connection Name A friendly identifier (e.g., "Acme Corp – UKG Pro Platform")
Client ID From your registered application
Client Secret From your registered application
Token Endpoint Your UKG OAuth 2.0 token URL
Audience The target API audience value
Organization (Tenant ID) Your UKG tenant identifier
API Base URL Your UKG Pro Platform API base URL

Proceed to Section 7 to transmit these credentials securely to Wisq.

7. Provide Credentials to Wisq

Because this integration involves privileged API access, credentials must be transmitted securely.

For Basic Authentication, you are transmitting a username, password, and API keys. These are highly sensitive and must be transmitted using one of the secure methods below.

For OAuth 2.0, the values you are sending (Client ID, Client Secret, Token Endpoint, Organization) define the scope of API access to your UKG environment and should be treated as sensitive.

Preferred Method: Encrypted Email

Examples:

  • Proton Mail
  • Microsoft Purview Message Encryption
  • Mimecast Secure Messaging

Send to your Wisq Agent Strategist contact.

Please do not send credentials in plain text email, chat platforms, or ticket systems.

8. Final Checklist

Basic Authentication with API Keys

  • [ ] Service Account created with a secure password (Section 3)
  • [ ] Service account permissions configured for required services (Section 4)
  • [ ] Customer API Key recorded (Section 5)
  • [ ] User API Key recorded (Section 5)
  • [ ] API Base URL confirmed (Section 6A)
  • [ ] Username recorded
  • [ ] Password saved securely
  • [ ] Credentials transmitted securely to Wisq (Section 7)

OAuth 2.0 Client Credentials

  • [ ] Application registered and Client ID recorded (Section 6B, Step 1)
  • [ ] Client Secret recorded securely (Section 6B, Step 1)
  • [ ] Token Endpoint URL recorded (Section 6B, Step 2)
  • [ ] Audience value confirmed (Section 6B, Step 2)
  • [ ] Organization (Tenant ID) recorded (Section 6B, Step 1)
  • [ ] API Base URL recorded (Section 6B, Step 3)
  • [ ] Credentials transmitted securely to Wisq (Section 7)

Need Assistance?

If your IT team would like support during configuration, Wisq's Agent Operations team is happy to join a working session.

Confidential — For Client IT Teams Only