Workday integration system user setup, in order

Giving an integration or an AI tool API access to Workday is five steps, done in this order: create the integration system user (ISU), put it in an integration system security group, grant that group permission on the domains the integration needs, register an API client for it, and generate its refresh token. Skip a step or do them out of order and the symptom shows up later as a 401, a 403, or an invalid_grant — nowhere near the step that actually caused it.

Create the integration system user

Run the Create Integration System User task. Give it a name that says what it is for, not who set it up, and set a password. Three settings matter more than the rest:

  • Do Not Allow UI Sessions — select it. This account exists to answer API calls, not to sign in through a browser. Checking it removes the sign-in page as an attack surface for the account entirely, so a leaked password still can't be used to log in and click around.
  • Session Timeout Minutes — leave it at zero, Workday's default for an ISU. A nonzero timeout expires the underlying session and can stop a long-running integration mid-task.
  • Require New Password at Next Sign In — leave it unchecked; an ISU with UI sessions disallowed has no sign-in flow to complete it.

Then open the Maintain Password Rules task and add the ISU to the System Users Exempt from Password Expiration field. Without that, Workday's tenant-wide password-expiration policy applies to the ISU's password like any person's, and when it expires the integration starts failing for a reason that has nothing to do with its API client or refresh token.

Put the ISU in an integration system security group

An ISU has no access by itself. Run Create Security Group and choose Integration System Security Group as the type, then decide constrained or unconstrained:

  • Unconstrained gives the group access across the whole tenant's data, not limited to specific organizations. Use it for a tenant-wide integration, such as a payroll feed or an AI tool that needs to look up any worker by name.
  • Constrained limits the group to workers in the organizations you assign to it. Use it when the integration should only ever see one business unit or region.

Assign the ISU to the security group from the group's related-actions menu. One ISU can belong to more than one group, but keep a single-purpose integration on a single group — it is what makes a permission audit or an incident review possible later.

Grant the domain security policy permissions

Membership in a security group grants nothing on its own; a domain security policy has to name that group and say what it can do. Open the domain security policy for each domain the integration touches (for example, the domain behind the worker data or business process you're integrating) and add the security group in the column that matches the API it will call:

  • REST APIs, including WQL and report calls over REST need Report/Task Permissions: View for reads (GET) and Modify for writes (POST, PUT, PATCH, DELETE). This applies to an ISU exactly as it does to a person.
  • SOAP web services need Integration Permissions: Get for reads and Put for writes. Workday applies these to SOAP only, so Get and Put alone leave a REST call with a 403.

Saving that change is not the end of it. Workday holds security policy edits as pending until you run Activate Pending Security Policy Changes. A group correctly added to a policy still has no effect until that activation runs — this is one of the more common reasons "the security is set up right" produces a 403 anyway. Group membership changes, by contrast, take effect immediately and don't need activation.

Register API Client for Integrations vs. Register API Client

Workday has two client-registration tasks and they are not interchangeable. For a service or an AI tool that runs unattended, use Register API Client for Integrations: give it a client name, select Non-Expiring Refresh Tokens, and choose the Scope (Functional Areas) that covers what the integration does, such as System for WQL, never every area by default. A REST endpoint's scope is the functional area its reference lists beside the securing domain. Click OK and save the Client ID and Client Secret it shows you once.

Register API Client, the other task, is for an interactive flow where a real person completes a browser authorization step — a Client Grant Type of Authorization Code Grant, typically with Proof Key for Code Exchange (PKCE), and a redirection URI the browser returns to. That flow is right for a kiosk or a user-facing app; it is the wrong one for a service account that never has a browser session to redirect.

With the client registered for integrations, open View API Clients, find the client on the API Clients for Integrations tab, and from its related-actions menu choose Manage Refresh Tokens for Integrations. Select the ISU in the Workday Account field and generate the token. Save the refresh token value now — Workday shows it once, on the confirmation page, and does not display it again.

Exchange the refresh token for an access token

Every access token comes from a token request to the tenant's own OAuth endpoint, shaped like this (fill in your tenant's actual host and tenant name): 

POST <tenant host>/ccx/oauth2/<tenant>/token
Authorization   Basic <base64 of the client id and client secret>
Content-Type    application/x-www-form-urlencoded

grant_type       refresh_token
refresh_token    <the refresh token value>

A successful exchange returns a short-lived bearer access token, shaped like this:

{
  "access_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600
}

The refresh token from Manage Refresh Tokens for Integrations does not expire on its own. The access token it produces does — request a new one each time the old one is close to its expires_in window rather than caching it indefinitely.

Prove access with the smallest possible read

Before wiring the credential into an integration or an AI tool, prove it works with one request that changes nothing: a single-record read against a domain the ISU's group has View access to. 

GET <API gateway host>/common/v1/workers?limit=1
Authorization: Bearer <access_token>

A 200 with one record proves the whole chain — ISU, security group, domain permission, activation, client scope, and refresh token — end to end. Test a write the same way, with one record, before pointing the integration at production volume.

What the common errors actually mean

  • invalid_grant on the token request usually means the refresh token itself is wrong, expired for a client that isn't using non-expiring tokens, or was issued to a different client ID than the one in the request. Regenerate it from Manage Refresh Tokens for Integrations and confirm you copied the whole value.
  • invalid_client means Workday couldn't match the client ID and secret you sent, most often a copy-paste error or the wrong client (an authorization-code client's ID used where an integrations client's ID belongs).
  • 401 on the API call means the access token itself is missing, expired, or malformed — request a fresh one from the token endpoint.
  • 403 on the API call means the token is valid but the ISU's security group lacks the right permission on that domain (View or Modify for REST, Get or Put for SOAP), the client lacks the endpoint's functional area in its scope, or the policy change was never activated. Check the domain security policy and Activate Pending Security Policy Changes before touching the client.
  • A refresh token that suddenly stops working is frequently the ISU itself: a changed password, a security group membership change, or a deactivated account revokes the tokens issued under it. When access breaks with no client or scope change on your side, check the ISU's own state first.

Where to go from here

Once the client authenticates, running a report or a WQL query over REST and writing the query itself are the next steps for read access. If the same credential drives an Extend orchestration rather than an external client, see Orchestrate errors and what they mean, including the separate credential-type failure that looks like this one but isn't. For pointing an AI assistant at Workday data once a client exists, see connecting Claude or ChatGPT to Workday.

Sources checked