What WCPISU is

WCPISU (Workday Cloud Platform Integration System User) is the legacy authentication scheme that lets an Extend page call Workday APIs as a preconfigured integration system user instead of as the signed-in person. An administrator stores a refresh token for the ISU in the tenant's credential store, and Presentation Components use it to get an access token before calling the endpoint.

Workday now calls it legacy. Existing apps can keep using it, but Extend apps created after October 4, 2024 must use the simplified ISU scheme, and that includes apps created by copying an older app. Reverting old code in an app that already existed in App Hub doesn't change the app's creation date, so older apps keep the option.

How the pieces fit together

A working WCPISU setup has four parts, and the names in them have to agree.

  1. An API client registered on the Developer Site (Console > API Clients) for your app. You need its client ID and secret.
  2. A refresh token for the ISU. You sign in to the tenant as the ISU and run an OAuth authorization code flow against your region's authorization base URL: https://{regionAuthBaseUrl}/v1/authorize for the code, then a POST to https://{regionAuthBaseUrl}/v1/token with grant_type=authorization_code, the code, and a Basic header of the Base64-encoded clientId:clientSecret. The code is valid for 10 minutes. The refresh token returned doesn't expire.
  3. A Cred Store entry, made with the Create External Client CredStore task (secured to the Security Administration domain). It holds the App ID, the client ID and secret, the authorization and token endpoints, and a Tokens grid row with the refresh token, the ISU's username as Token Holder, and Descriptor set to RefreshToken. Auth Scheme for External Client is OAuth 2.0 Authorization Code.
  4. An authType in the SMD that points at that entry, and PMD endpoints that use it.
"siteAuth": {
  "authTypes": [
    {
      "id": "wcpisu1",
      "scheme": "WCPISU",
      "appId": "equipmentRequest_abcdef",
      "tokenHolder": "EquipmentRequest_ISU",
      "checkEnvironment": "true"
    },
    { "id": "sso", "scheme": "SSO" }
  ]
}

An endpoint opts in by naming the id:

"endPoints": [
  {
    "name": "equipmentTotals",
    "baseUrlType": "workday-common",
    "url": "/workers/me",
    "authType": "wcpisu1"
  }
]

The credential store finds the right token by the pair appId + tokenHolder. appId is the app reference ID with your company ID suffix, as App Manager shows it, and it must equal the Cred Store App ID. For WCPISU the Cred Store's External Reference ID is the same value as the App ID. tokenHolder must equal the Token Holder in the Tokens grid. The default authType for any endpoint that doesn't name one is SSO.

One practical snag Workday documents: if the ISU's Workday account has Do Not Allow UI Sessions selected (on Edit Workday Accounts), you can't sign in as it to get the code. Clear the option, get the token, then select it again.

What checkEnvironment does

By default a WCPISU refresh token is used in every environment. In the Cred Store's Tokens grid, Used for Environments can restrict a token to particular tenant environments, but the restriction only applies if the SMD sets checkEnvironment to true. Workday recommends true for non-Development customer environments so a token can't be used outside the environments you listed.

Sandbox needs particular care. Workday says to create refresh tokens in both Sandbox and Sandbox Preview. If business objects exist in Sandbox Preview and that tenant has no refresh token, requests to those business objects return HTTP 500. If only Sandbox has tokens, the business objects work only in Sandbox.

What the simplified ISU scheme changes

Workday doesn't give its reasons beyond calling the simplified scheme improved and simpler, but the difference in setup is plain. WCPISU needs someone to sign in as the ISU, run the OAuth flow in a REST client such as Postman, and paste a non-expiring refresh token into Create External Client CredStore in each tenant, with three hand-typed values (appId, tokenHolder, App ID) that must agree.

The simplified ISU scheme replaces that with an App Manager action. You assign an ISU to the app with Add Integration System User and click Create API Client; Workday generates a tenant-specific API client. The SMD then needs only the ISU's username:

"siteAuth": {
  "authTypes": [
    { "id": "isuAuth", "scheme": "ISU", "username": "EquipmentRequest_ISU" }
  ]
}

Tenant refreshes are the other reason. Workday notes that with the simplified scheme you no longer have to worry about Implementation or Sandbox using Production credentials after a refresh; existing WCPISU apps keep working through a refresh because they're already configured.

Migrating an app from WCPISU to simplified ISU

Workday's migration path is short:

  1. In each tenant, create the ISU if needed (the Integration Security domain), then in App Manager open the app, click Configure, use Add Integration System User, and click Create API Client on the new row. Assigning needs the WCP Integration System User Security domain; it's what makes the button appear.
  2. Add an ISU entry to authTypes in the SMD with the ISU's username.
  3. In every PMD endpoint that names the WCPISU id, replace authType with the ISU entry's id.
  4. For orchestrations, create an ISU credential on the orchestration's Credentials tab (in Settings) and put the ISU's name in the Username expression.
  5. For each non-Development tenant, have a Company Administrator open Console > API Clients on the Developer Site and add the tenant under Modify Authorized Tenants on that tenant's API client.

You can't reuse the API client from the WCPISU setup for the simplified scheme; Workday says so explicitly. Each ISU can be associated with only one app.

Remove the WCPISU authTypes entry only after no endpoint names its id any more. The simplified ISU errors guide covers what goes wrong after the switch.

Testing a WCPISU endpoint

App Preview connected to a tenant honours WCPISU: it's in the documented list of authType values the preview supports when connected, alongside SSO, NoAuth, OAuth client credentials and AWSV4. Without a tenant connection, App Preview ignores authType entirely, so a preview that isn't connected proves nothing about the ISU.

To prove the endpoint runs as the ISU, open the page as a test user who has no access to the domain behind the endpoint. If the page still shows the data, the ISU's token was used. Then check who can open the page at all. Workday's security guidance calls ISU authentication always a security exception, because the ISU's access doesn't follow the end user's, so the app has to restrict the page with its own security domains or check the user's roles itself.

When a WCPISU endpoint works in one tenant and not another, compare the Create External Client CredStore entries tenant by tenant (App ID, Token Holder, Used for Environments, and Sandbox Preview tokens) before looking at the code. For WCPISU problems that surface as token or 401 errors on the Workday side, ISU authentication errors covers the account and security group checks.

Sources checked