Workday HCM connector

The Workday HCM connector imports workers and supervisory organizations from your Workday tenant via the modern REST API. Phase 1 is read-only — IdentityMesh treats Workday as the source-of-truth for employee master data and projects worker records into the mesh, where they can be joined with downstream identity systems (AD, Entra ID, Okta) by the same join rules that already drive your AD ↔ Entra integration.

Overview

If you operate Workday as your HRIS and Active Directory or Entra ID as your identity provider, run this connector alongside the AD or Entra connector — they project into the same mesh objects, and the merge is governed by the join rules configured in the Admin UI (typically join on employeeNumber or email).

Prerequisites

• A Workday tenant where you can create an Integration System User (ISU) and grant OAuth2 application access. Workday admin or HR Admin role is typically required for this setup.
• The tenant’s API host (e.g. wd5-impl-services1.workday.com) and tenant name (e.g. contoso_preview) — both visible from the Workday admin home page or the URL operators use to log in.
• The IdentityMesh Sync Engine has the connector DLL installed in its Connectors/ folder (shipped in the MSI from the version that lands ER-019).

Workday tenant setup

1. Register the integration application in Workday:

   • Open Edit Tenant Setup - Security and enable OAuth 2.0 Clients for Integrations.
   • Run the Register API Client for Integrations task. Provide a friendly name (e.g. IdentityMesh-prod) and select a Workday account that becomes the integration system user (ISU).
   • On completion, Workday returns the Client ID and the one-time Client Secret. Save both immediately — the secret cannot be retrieved later.

2. Grant the ISU read access to the worker and organization data. Recommended security groups:

   • Worker Data: Public Worker Reports
   • Worker Data: Active and Terminated Workers
   • Organization Data: View Organization

   Avoid blanket System Administrator grants. Document the exact security groups in your change-control system; Workday audits every change to ISU permissions.

3. Test the OAuth2 token endpoint from a workstation:

   curl -X POST \
     "https://{tenant}.workday.com/ccx/oauth2/{tenant_name}/token" \
     -d "grant_type=client_credentials" \
     -u "<client_id>:<client_secret>"

   A successful response contains an access_token valid for ~30 minutes.

Configure IdentityMesh

1. Provision the secret via secretscli:

   secretscli set secret://workday/{tenant_name}/clientsecret "<the secret>"

2. Create the connector via the Admin UI or REST. Sample configJson:

   {
     "TenantHost": "wd5-impl-services1.workday.com",
     "TenantName": "contoso_preview",
     "Realm": "contoso_preview",
     "PageSize": 100,
     "ImportWorkers": true,
     "ImportOrganizations": true,
     "ImportPositions": false,
     "ExternalIdAttribute": "id"
   }

   Realm typically equals TenantName; some Workday tenants distinguish between the two — check with your Workday admin.

3. Wire the secret reference on the connector’s AuthMaterial: a single ref string of the form secret://workday/{tenant_name}/clientsecret. The auth materializer resolves it at run time.

4. Add a join rule in the Admin UI mapping Workday.employeeNumber → mesh.employeeNumber (or whatever anchor your existing AD / Entra connectors use). This is what joins a Workday worker into an existing mesh object created by the IdP connector.

What gets synced

Worker → User

payRate and other compensation fields are deliberately excluded in phase 1. Sensitive payroll data lives on a different audit / permission boundary; phase 2 will let operators opt in per attribute.

Supervisory Organization → OrgUnit

Organization membership is not emitted as a separate GroupMember object type. Each worker carries primaryWorkerSupervisoryOrganization as an attribute, which is sufficient for downstream join rules to project users into the right group / OU. Customers needing flat membership rows should file a phase-2 request.

Watermark and delta behaviour

Watermarks are ISO-8601 lastUpdatedDateTime timestamps stored per object type, encoded as a single JSON string the engine treats opaquely:

{"w": "2026-04-26T08:30:00.000Z", "o": "2026-04-26T08:25:00.000Z"}

(w = workers, o = organizations)

The connector tolerates legacy bare-string watermarks for in-flight upgrades — if it sees a plain ISO timestamp instead of the wrapper, both feeds use that timestamp as their starting point.

Hard-delete gap

Workday does not typically purge worker records — terminated workers retain a Terminated employment status and remain visible in the API indefinitely. The connector maps employmentStatus == "Terminated" to ChangeType.Delete + IsDeleted=true, which is the correct soft-delete signal for downstream provisioning.

If your Workday tenant is configured to purge worker records (rare, but possible for contingent workers), schedule a periodic full sync (set the connector’s Mode = Full on a weekly cadence) to catch hard-deletes. Phase 2 will close this gap via the Workday Audit report API.

Throttling

Workday’s REST API enforces per-tenant rate limits (configurable per Workday environment). The connector handles 429 Too Many Requests responses with Retry-After-aware retry: 3 retries with exponential back-off capped at 30 seconds. Beyond that it surfaces the error to the run history.

If you see frequent 429s in the connector logs, work with Workday Support to raise the integration tenant’s rate limit — IdentityMesh makes one request per page (100 workers per page by default), so even a 100k-worker tenant fits inside the standard 1000 req/hour bucket.

Security model

• App-only auth — no user impersonation; the OAuth2 token represents the ISU, not a logged-in user.
• Read-only scope — the recommended security groups grant read access only. Workday’s audit log records every API call the ISU makes; review it after the first sync to confirm the call pattern matches expectations.
• Secret rotation — rotate the OAuth2 client secret every 12 months minimum (more often if your security policy mandates). The rotation procedure is the same as any other secret managed through secretscli; see secret-rotation.md.

Phase 2 backlog

The following are out of scope for the phase 1 ship and are documented as follow-ups:

• Export / write-back — provisioning HR-side changes (job changes, terminations) back into Workday from the mesh
• SOAP Worker_Get fallback — for older Workday tenants where the REST API doesn’t expose all fields
• Position object type — distinct from workers; some customers model positions as first-class identities
• Compensation / payRate — sensitive payroll fields with their own permission boundary
• Profile photos / file attachments — Workday workers can carry binary attachments; phase 2 will resolve them via URLs
• Custom fields — Workday lets customers extend the worker schema; phase 2 will surface custom fields as dynamic mesh attributes
• Workday Audit report integration — for true hard-delete detection without periodic full syncs

Related runbooks

• secret-rotation.md — secret lifecycle
• secrets-keyvault.md — vault-backed secret storage when DPAPI isn’t enough (Azure)
• secrets-vault.md — vault-backed storage for HashiCorp customers
• connector-entra.md — pair Workday with Entra ID to project HR data into your cloud directory
• connector-okta.md — pair Workday with Okta to drive provisioning from the source-of-truth
• relay-agent.md — for Workday tenants behind a customer firewall (rare; Workday is SaaS)