Skip to content

guides

Intended Documentation

Workday Connector Setup (Beta)

Connect Intended to Workday HCM. Register an API client with the refresh-token grant, paste the host, tenant, client ID/secret, and refresh token, and run Test connection. Host-pinned to *.workday.com / *.myworkday.com. Beta until validated against your live tenant.

intermediate3 min readpartial
PartialSource: codeValidated: 2026-07-09

Workday Connector Setup (Beta)#

Connect Intended to Workday so approved intents can hire a worker and approve a time-off request through the real Workday HCM adapter (packages/execution-engine/src/adapters/workday.ts). Auth is an OAuth 2.0 refresh-token grant. Every write is Authority-Token-verified, ESCALATEs for approval under the starter policy, and carries an X-Idempotency-Key.

This connector is Beta

The adapter is real and covered by hermetic (mocked-HTTP) tests that pass in CI with no live tenant. Live proof against your real Workday tenant is pending — treat Workday as Beta, not GA. See the Capability Truth Matrix.

What the adapter does#

PropertyValue
Actionsworkday.worker.hire, workday.timeoff.approve
AuthOAuth 2.0 refresh-token grant; client creds via HTTP Basic → Authorization: Bearer <token>
Host pinThe resolved origin must end with .workday.com or .myworkday.com (or equal workday.com / myworkday.com). HTTPS required; embedded credentials, cloud-metadata, loopback/link-local/RFC1918 hosts blocked
Test connectionRuns the refresh-token grant, then GET /ccx/api/v1/{tenant}/workers?limit=1

The token endpoint and API base are the same validated origin: token at {origin}/ccx/oauth2/{tenant}/token, API at {origin}/ccx/api/v1/{tenant}.

Provider-side steps#

1. Register an API client (refresh-token grant)#

  1. In Workday, search the Register API Client task.
  2. Register an API Client for Integrations using the Authorization Code Grant so you can obtain a refresh token, scoped to the functional areas below.
  3. Copy the Client ID (clientId) and Client Secret (clientSecret).

2. Obtain a refresh token (refreshToken, required)#

Complete the authorization flow once for the integration system user to obtain a durable refresh token.

3. Host and tenant#

  • host — your Workday host, e.g. impl-services1.wd12.myworkday.com.
  • tenant — your tenant identifier (the {tenant} path segment).

Least-privilege scope guidance#

  • Matrix capabilities: staffing:write, timeoff:write.
  • Scope the API client's functional areas to Staffing (for workday.worker.hire) and Time Off / Absence (for workday.timeoff.approve) only, via a constrained Integration System Security Group.
  • Do not grant tenant-wide security groups the actions don't require.

Fields to paste into the connect dialog#

Open Connectors → Connect a system → Workday → Configure auth:

Field labelKeyRequiredValue
Workday HosthostYesimpl-services1.wd12.myworkday.com
TenanttenantYesYour tenant identifier
OAuth Client IDclientIdYesThe API client id
OAuth Client SecretclientSecretYesThe API client secret
Refresh TokenrefreshTokenYesThe OAuth refresh token

Credentials are stored per-tenant, AES-256-GCM-encrypted, and never displayed back.

Run Test connection#

  1. Finish the connect wizard to store the credential.
  2. On the connector card, click Test connection.
  3. The adapter performs the refresh-token grant against {host}/ccx/oauth2/{tenant}/token, then calls GET {host}/ccx/api/v1/{tenant}/workers?limit=1 with the Bearer token. A green result means the host passed the *.workday.com / *.myworkday.com pin, the client authenticated, and the API answered the read. The probe therefore also needs a workers read (Staffing/Common view) in the client's scope.

Next steps#

Workday Connector Setup (Beta) | Intended