UKG Pro API authentication: Customer API Key, User API Key, and web service account

Key takeaways

• The Customer API Key identifies the tenant. The web service account (a username and password) identifies the caller. The User API Key belongs to that account and is used at SOAP login.
• Core HCM REST calls carry two things: a US-Customer-Api-Key header and HTTP Basic auth built from the service account's username and password. UKG's REST reference lists no User API Key header.
• SOAP calls start at the Login Service, which takes all four values in the SOAP header: ClientAccessKey, UserAccessKey, UserName, and Password.
• Newer Pro Platform APIs use Developer Console client credentials instead: a Client ID and Client Secret exchanged for a bearer token, sent with a global-tenant-id header.
• A 401 means UKG didn't accept the credentials. A 403 means it did, and the service account hasn't been granted that web service.

UKG Pro API authentication: Customer API Key, User API Key, and web service account

UKG Pro gives an engineer three things with similar names: a Customer API Key, a User API Key, and a web service account. The service account brings a fourth value, its password. UKG documents each of them, but on different pages and for different API styles. So when the first call fails, the wrong key usually gets the blame.

Here is the model in one place. The Customer API Key identifies the tenant. It's a five-character key unique to each UKG Pro customer, shown under System Configuration > Security > Web Services. The web service account identifies the caller. It's a non-human user with its own username, password, and permissions, created in Service Account Administration. The User API Key belongs to that account. UKG assigns one per web service account, and the SOAP services check it at login.

Which of these a request carries depends on which API you're calling.

Where each credential goes: REST vs SOAP

UKG's REST endpoint reference is specific about the REST side. Each core HCM endpoint takes a US-Customer-Api-Key header and an Authorization header that is Base64 of {username}:{password}. That's standard HTTP Basic auth as RFC 7617 defines it. The password in that pair is the web service account's password. Putting the User API Key there instead is one of the most common first 401s.

curl "https://{service_host}/personnel/v1/person-details" \
  -H "Authorization: Basic {base64(service_account_username:password)}" \
  -H "US-Customer-Api-Key: {customer_api_key}"

# {service_host} is tenant specific, e.g. service4.ultipro.com.
# The service account needs the View role on the Personnel Integration web service.

The SOAP side is where the User API Key does its work. UKG's Login Service takes all four values as elements in the SOAP envelope's header and returns a token for the other SOAP services. UKG's C# sample names its variables CustomerApiKey and UserApiKey, but the XML elements are ClientAccessKey and UserAccessKey. If you're writing the envelope yourself, use the element names.

  
    http://www.ultipro.com/services/loginservice/ILoginService/Authenticate
    {customer_api_key}
    {password}
    {user_api_key}
    {username}
  
  
    
  

That also explains why a search for a US-User-Api-Key header turns up so little. UKG's REST reference doesn't list one. On REST, look for one custom header and one Basic auth pair. On SOAP, look for four header elements.

Two auth paths: web service account vs Developer Console OAuth

Everything above is UKG's older credential model. Newer UKG Pro Platform APIs use a different one. In Pro HCM, an admin opens System Configuration > Security > Developer Console, creates a client, and copies its Client ID and Client Secret along with the organization, token URL, and audience shown on that page. The OAuth 2.0 client-credentials grant from RFC 6749 exchanges those for a bearer token. Calls then carry Authorization: Bearer {token} and the organization in a global-tenant-id header, per UKG's bearer token recipe.

The two paths also age differently. A web service account's password and keys last until someone rotates them. Bearer tokens expire, and UKG tells integrators to renew from the expires_in value in each token response. If you've read two different figures for how long a UKG credential stays valid, check which path each one described.

Which path an endpoint takes is set in that endpoint's reference. Core HCM REST endpoints documented with Basic auth still use a web service account. For the full map across Recruiting, Onboarding, and WFM, see our UKG Pro API authentication and architecture guide.

Why a valid-looking call still returns 401 or 403

RFC 9110 separates the two. A 401 means the server didn't accept the credentials: missing, malformed, or wrong. A 403 means it understood who you are and refuses anyway.

For UKG Pro, the 403 is the one that eats afternoons. UKG grants a web service account permission per web service, down to resource and method. An account can authenticate cleanly and still be refused on any service it hasn't been given. Reading people, for example, needs the View role on the Personnel Integration web service. UKG also warns against treating every 401 or 403 as an expired token, because the same status can come from a permission or configuration problem. Our guide to the employee, payroll, and benefits data UKG Pro exposes covers which web services hold which records.

Before assuming the keys are bad, check four things:

Every new endpoint means a permission check. Every new customer means the whole handshake again, with their account and their key.

Handling this per customer, at scale

For one tenant, creating the service account, granting permissions, and wiring up the headers takes an afternoon. For a product connecting hundreds of employers to UKG Pro, it's the same handshake per tenant, plus password rotations, revoked permissions, and admins who grant the wrong role.

Bindbee is a unified API for 67+ HRIS, payroll, ATS, and benefits systems, UKG Pro among them. Its UKG Pro connector uses the core HCM REST path on this page. Your customer's UKG admin creates a service account, grants the web services your use case needs, and enters it with the Customer API Key through a Magic Link, following Bindbee's UKG Pro setup guide. If those credentials later stop working, the connector is relinked, not rebuilt.

Syncs run every 24 hours by default, and the schedule can be changed per connection. Bindbee's webhooks fire when a sync starts, finishes, or fails, and when a sync finds created or updated records. So a UKG credential that stops working shows up at the next sync as a sync error, not as quietly stale data.

Identity, placement, and permission are three separate problems, and a 401 or 403 is UKG telling you which one you're looking at. We build the integrations. You build the product.

Frequently asked questions

What is the difference between the UKG Customer API Key and the User API Key?

The Customer API Key identifies the tenant, the UKG Pro customer a call belongs to. The User API Key belongs to one web service account and is checked when that account logs in to UKG's SOAP services. Core HCM REST calls use the Customer API Key plus the account's username and password.

Is there a US-User-Api-Key header in the UKG Pro REST API?

UKG's REST endpoint reference doesn't list one. Core HCM REST endpoints take a US-Customer-Api-Key header and HTTP Basic auth built from the web service account's username and password. The User API Key goes to the SOAP Login Service, as the UserAccessKey element.

Why does my UKG API call return 401 or 403 when my keys are correct?

A 401 usually means the Basic auth pair or Customer API Key wasn't accepted. Check that the password field holds the service account's password, not the User API Key. A 403 means UKG accepted the credentials, but the web service account hasn't been granted permission to that web service.

Does UKG Pro use OAuth or API keys?

Both. Core HCM REST and SOAP use a web service account with the Customer API Key, and SOAP adds the User API Key at login. Newer Pro Platform APIs use OAuth 2.0 client credentials from the Developer Console, with a bearer token and a global-tenant-id header.