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

# Workday API Authentication

> How Toku authenticates with Workday using a dedicated Integration System User

Toku connects to Workday as a dedicated **Integration System User (ISU)** placed in its own Integration System Security Group. The group carries least-privilege domain security policies scoped to the integration — your Workday administrator creates both during setup and can revoke access at any time. Toku's implementation team provides the exact scope list during onboarding.

## Authentication Mechanisms

Workday exposes three API surfaces, each with its own documented authentication mechanism. Toku uses the same ISU across all three:

| API surface                      | Mechanism                  | Used for                              |
| -------------------------------- | -------------------------- | ------------------------------------- |
| RaaS custom reports              | HTTP Basic (`user@tenant`) | Worker and payroll report sync        |
| Workday Web Services (WWS, SOAP) | WS-Security UsernameToken  | Payroll results and payroll input     |
| Workday REST                     | OAuth 2.0                  | Token-based REST access where enabled |

### HTTP Basic (RaaS)

Report requests authenticate with basic auth, using the username form `user@tenant`:

```bash theme={null}
curl -u "ISU_TOKU@acme_tenant" \
  "https://<host>/ccx/service/customreport2/<tenant>/<report_owner>/<Report_Name>?format=json"
```

### WS-Security UsernameToken (WWS)

SOAP calls carry the ISU credentials in a WS-Security header:

```xml theme={null}
<wsse:Security soapenv:mustUnderstand="1">
  <wsse:UsernameToken>
    <wsse:Username>ISU_TOKU@acme_tenant</wsse:Username>
    <wsse:Password Type="...#PasswordText">********</wsse:Password>
  </wsse:UsernameToken>
</wsse:Security>
```

### OAuth 2.0 (Workday REST)

<Steps>
  <Step title="Register">
    Your Workday administrator runs the tenant task **Register API Client for Integration**, which yields a client ID and client secret.
  </Step>

  <Step title="Generate">
    A non-expiring refresh token is generated for the Toku ISU from the registered API client.
  </Step>

  <Step title="Exchange">
    Toku exchanges the refresh token for short-lived access tokens at the tenant's token endpoint — the connection stays live without re-authorization.
  </Step>
</Steps>

```bash theme={null}
# Token exchange (performed by Toku's backend)
curl -X POST "https://<host>/ccx/oauth2/<tenant>/token" \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=<refresh_token>"
```

## Hosts

Workday hosts are tenant-specific — an implementation tenant might live at `wd2-impl-services1.workday.com`, while your production tenant lives elsewhere. Always copy the exact URL from your own tenant rather than reusing an example host.

<Note>
  After your administrator adjusts the ISU's security group, Workday requires running **Activate Pending Security Policy Changes** before the new access takes effect. See the [Workday Web Services directory](https://community.workday.com/sites/default/files/file-hosting/productionapi/index.html) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Worker Sync" icon="users" href="/integrations/workday/employee-sync">
    How Toku reads your worker roster via RaaS
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/workday/payroll-sync">
    How Toku tracks pay runs and payroll results
  </Card>
</CardGroup>