> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UKG Pro API Authentication

> How Toku authenticates with UKG Pro web services using a dedicated service account and API keys

Toku connects to UKG Pro using a [dedicated Service Account](https://developer.ukg.com/hcm/docs/web-service-account) that your UKG administrator creates and controls. Access is scoped by the web-service roles you grant the account — you can disable it at any time to cut off access instantly.

## Service Account Setup

<Steps>
  <Step title="Create the service account">
    Your UKG admin creates a Service Account for Toku under **Menu → System Configuration → Security → Service Account Administration**, granting only the web-service roles Toku needs.
  </Step>

  <Step title="Collect the API keys">
    The same page shows your tenant's **Customer API key** and the service account's **User API key**. Both are entered into Toku along with the account credentials.
  </Step>

  <Step title="Connect from Toku">
    In **Settings → Payroll Integrations → UKG**, enter your tenant base URL, service account credentials, and API keys. Toku validates the connection with a read-only test call.
  </Step>
</Steps>

## REST Requests

UKG Pro's REST Core APIs use HTTP Basic authentication with the service account credentials, plus the `US-Customer-Api-Key` header carrying your tenant's Customer API key:

```bash theme={null}
curl "https://<hostname>.ultipro.com/personnel/v1/person-details" \
  -H "Authorization: Basic <base64(username:password)>" \
  -H "US-Customer-Api-Key: <customer_api_key>"
```

Your tenant base URL (e.g. `https://<hostname>.ultipro.com`) is unique to your environment — find it in UKG Pro under **System Configuration → Security → Web Services**.

## SOAP Login Service

Some payroll integration services are SOAP-based. For these, Toku first calls UKG's [Login Service](https://developer.ukg.com/hcm/docs/login-service) at `https://<hostname>/services/LoginService` with four headers — `UserName`, `Password`, `UserAccessKey` (the User API key), and `ClientAccessKey` (the Customer API key) — and receives a login token used on subsequent SOAP calls. Tokens are short-lived and rotated automatically.

## Permissions

UKG Pro scopes service accounts through per-domain web-service roles — for example, **View** on *Employee Person Details*, *Employee Compensation Details*, and *Personnel Integration*, and **Add** on *Payroll Integration*. Toku requests the minimum set needed for stablecoin payroll; the exact permission list is provided by Toku's implementation team during onboarding.

Any call outside the granted roles is rejected by UKG Pro. Disabling the service account or rotating its keys immediately revokes Toku's access.

## Environments

| Environment                                      | Base URL                                      |
| ------------------------------------------------ | --------------------------------------------- |
| Production                                       | `https://<hostname>.ultipro.com` (per-tenant) |
| Test tenant (used during implementation testing) | Provided by UKG for your account              |

<Note>
  See UKG's documentation on [service accounts](https://developer.ukg.com/hcm/docs/web-service-account) and the [Login Service](https://developer.ukg.com/hcm/docs/login-service) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Employee Sync" icon="users" href="/integrations/ukg/employee-sync">
    How Toku reads your employee roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/ukg/payroll-sync">
    How Toku tracks pay groups and upcoming payrolls
  </Card>
</CardGroup>