UKG Ready API credentials: OAuth client credentials, API keys, and the security profile

Key takeaways

• UKG Ready supports two ways in: an OAuth application issuing a client ID and secret, which is the method UKG's Ready documentation describes, and a legacy company API key plus service-account login that many vendor integrations still use.
• Both models are scoped by a security profile, which decides what the integration can read or write.
• For the OAuth model, a tenant admin creates a Machine to Machine OAuth application in Settings > Global Setup > Company Setup > OAuth Applications.
• For the legacy model, the API key is company-wide: don't regenerate it if other integrations already use it, because the old key stops working for all of them.
• UKG Ready documents a 7-day refresh-token lifetime; other UKG products publish different numbers, so read expires_in instead of hardcoding one.
• Rotate the service-account password or client secret on any personnel or vendor change, and immediately if it's exposed.

UKG Ready's API authentication looks simple from the outside: get credentials, request a token, call the API. The catch is that Ready tenants can be set up for two different credential models, and the setup checklists online mix them up with each other and with UKG Pro's.

Hand a customer's admin the wrong checklist and they'll create a service account when your integration expects an OAuth application, or generate a new API key that silently breaks every other integration on the tenant.

This guide lists every credential each model needs, the order to provision them in, how to scope the security profile to least privilege, and which token lifetimes apply to Ready.

What credentials does a UKG Ready API connection need?

It depends on which of Ready's two models the connection uses.

UKG Ready's REST documentation describes the OAuth model, and says the client-credentials flow is the one to use for machine-to-machine integrations. The legacy model predates it and is still what many vendors' setup guides ask for. Neither is wrong for a given tenant; what matters is that the customer's admin and your integration agree on one.

Which model applies to you?

If you're building the integration, ask which model your consumer supports before the admin provisions anything. If you're the admin, ask the vendor. For how these fit alongside UKG Pro and Pro WFM, see our guide to the UKG API landscape, and for how Ready's API is laid out once you're in, see our guide to UKG Ready API architecture and authentication.

Provisioning the OAuth application

1. Create the security profile: in Settings > Profiles/Policies > Security, define a profile with only the permissions the integration needs (next section).
2. Create the OAuth application: in Settings > Global Setup > Company Setup, find the OAuth Applications widget and add an application of type "Machine to Machine".
3. Attach the security profile to the application's client credential, so the token inherits exactly what the profile grants.
4. Store the client secret straight into a secrets manager, then hand the client ID, client secret, company ID, and hostname to whoever runs the integration.

curl -X POST "https://$HOST/ta/rest/v2/companies/$COMPANY_ID/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials"

Keep one application per integration. Separate credentials let you revoke one vendor without touching the others, and make it obvious in logs which integration did what.

Provisioning the legacy API key and service account

1. Create the security profile in Settings > Profiles/Policies > Security.
2. Create the dedicated service account: a new, non-human user, separate from any employee's login, and assign it the security profile.
3. Find the company API key in Settings > Global Setup > Company Setup > Login Config. If a key already exists and other integrations use it, don't regenerate it. A new key replaces the old one for every integration on the tenant.
4. Collect the company short name and domain: both appear in the tenant's login URL, and the admin can confirm them.

# Legacy login: check the tenant's REST reference for the exact request
curl -X POST "https://$HOST/ta/rest/v1/login" \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"username": "SERVICE_ACCOUNT", "password": "PASSWORD", "company": "COMPANY_SHORT_NAME"}}'

The response returns a token that subsequent calls present. Provisioning the credentials is necessary, but it doesn't make them safe: a broadly created security profile grants far more than most integrations should touch.

Scoping the security profile to least privilege

In both models, the security profile decides which employee data the integration can reach. Grant only what the integration reads, the practice known as least privilege. As an example, one vendor's UKG Ready setup guide (Thrive Learning, for an employee-data sync) scopes its profile to these datasets:

• Employee Information
• Account/Personal Information
• Cost Centers
• Dates
• Demographics
• Jobs
• Managers
• Profiles

Beyond the datasets, the profile also has to grant view, and edit only where needed, on specific REST API resources:

Your list will differ with your use case: a time-and-attendance integration needs timesheet and accrual resources, and a benefits integration may need pay information. The same principle, granting only what a given integration touches, applies well past UKG Ready. See our guide to employee data field scoping for the general pattern.

Which token lifetimes apply to UKG Ready?

UKG Ready's documentation says refresh tokens from its OAuth flow expire after 7 days, and each access token reports its own lifetime in expires_in (UKG's sample is about 30 minutes). UKG's Pro WFM documentation gives different numbers, 30-minute access tokens and 8-hour refresh tokens, and says both can change without notice.

So treat any "UKG token lifetime" you find online as belonging to the product it was measured on, and build renewal around expires_in rather than a fixed timer.

Storing, rotating, and consuming these credentials safely

Managing an API key, service-account password, or client secret means managing its full lifecycle, not only generating it once: centralized storage, access control, rotation, revocation, and auditing, per the OWASP Secrets Management Cheat Sheet. In practice:

• Store the API key, service-account password, and any OAuth client secret in a secrets manager, never in source or config files.
• Grant the security profile only what the integration reads.
• Rotate the service-account password or client secret on any personnel or vendor change.
• Rotate any credential immediately if it's suspected of exposure. For the legacy model, remember that regenerating the company API key affects every integration using it, so coordinate first.

Something still has to hold these credentials and call the API on an ongoing basis, whether that's a script your team maintains or a vendor's integration platform, and it authenticates through the same security profile you just created.

Bindbee is one example of that downstream consumer. It connects to UKG Ready with the tenant's own API credentials, never by logging into the UI and scraping screens. Once connected, it reads and writes within whatever the security profile grants, with a 24-hour default sync that can be adjusted per connection, and webhooks that fire when a sync finishes or fails, or when a sync finds changed records, so your system doesn't have to poll.

If you're evaluating a vendor to hold these credentials on your behalf, check its security posture directly. Review Bindbee's security posture rather than taking it on faith.

The credentials themselves are simple enough to list. What trips most integrations up is provisioning one model when the other side expects the other, or applying another UKG product's token numbers to a Ready tenant. Agree on the model first, scope the profile tightly, and the rest is careful sequencing.

For a team that would rather consume UKG Ready, and the other 102+ HRIS, payroll, ATS, and benefits systems Bindbee connects to, through one API than run this provisioning per customer, that's what Bindbee is built for. We build the integrations. You build the product.

Frequently asked questions

Does UKG Ready use OAuth or an API key?

Both exist. UKG Ready's documentation describes OAuth applications, with the client-credentials flow for machine-to-machine integrations. Many existing integrations use the older company API key plus a service-account login. Confirm which one the consuming integration supports before provisioning.

How long do UKG Ready OAuth tokens last?

Refresh tokens expire after 7 days, per UKG Ready's documentation, and each access token states its lifetime in expires_in. UKG Pro WFM publishes different numbers, so don't reuse them for Ready.

What should the security profile grant?

Only what the integration reads. A typical employee-data scope covers datasets such as Employee Information, Account/Personal Information, Cost Centers, Dates, Demographics, Jobs, Managers, and Profiles, plus view (and edit only where required) on REST resources like Employees, Employees (Changed), and Employees (me).

What do I do if a credential is exposed?

Rotate it immediately: revoke the old value, issue a new one, and update whatever consumes it. If it's the legacy company API key, every integration on the tenant needs the new key, so plan the cutover.