What these errors mean

A simplified ISU error usually means the ISU setup is missing or incomplete in the tenant you're running in, not that the code is wrong, especially when the same app works in another tenant. The simplified ISU scheme is configured tenant by tenant: an ISU assigned to the app in that tenant's App Manager, an API client created for it there, consent for that tenant on the API client if it isn't a Development tenant, and permissions on the ISU's security group.

Workday doesn't publish a reference for the message "ISU is not configured in this tenant for appRefId", and it doesn't document what a 500 from an ISU-authenticated endpoint means. The wording points at the pairing of a tenant and an app reference ID, which is exactly what the App Manager assignment creates. The checks below follow Workday's setup pages in the order the setup is built, so the first one that fails is the likely cause.

How the simplified ISU scheme resolves a request

When a page endpoint names an ISU authType, the SMD entry carries only a username:

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

That username is the ISU account you assigned to the app in App Manager. Assigning it is what produces the API client the endpoint authenticates with: Workday's ISU reference describes Presentation Components authenticating through the client generated during the App Manager ISU setup. Orchestrations do the same through an ISU credential on the orchestration's Credentials tab, where the Username expression is the ISU's name.

So the request depends on a chain: SMD username → ISU assigned to this app in this tenant → API client for this app, tenant and ISU → this tenant authorized on that client → ISU's security group permitted on the API's domain. A break anywhere fails the call.

Check 1: the ISU is assigned to the app in this tenant

In the failing tenant, open App Manager, select the app and click Configure. In the Integration System Users section there should be a row for the ISU named in the SMD.

If there's no Add Integration System User button, the person looking lacks the WCP Integration System User Security domain in the System functional area; Workday says that domain is what enables the button. Create a policy with Modify for the right group and run Activate Pending Security Policy Changes.

If the ISU you want isn't offered, two documented rules apply. The window lists only unassigned ISU accounts, and an ISU can be associated with only one app. If another app already holds it, create a separate ISU for this one. Creating ISUs needs the Integration Security domain in the Integration functional area.

After promotion, don't assume the Development setup carries forward. Workday's concept page states that promoting an app that uses the simplified ISU to a non-Development tenant requires the same ISU setup in that tenant.

Check 2: the API client exists for that ISU

On the ISU's row in App Manager, Create API Client must have been run. The generated client's name follows the pattern App: Env: Tenant: ISU: with the values filled in. On the Developer Site, Console > API Clients, All Clients tab, search for app: or isu: to find it.

If it isn't there, run Create API Client from App Manager. You can't substitute the API client from a legacy WCPISU setup; Workday says the simplified scheme can't be configured with those existing clients. And be careful deleting clients: Workday warns that removing an API client can break apps using it, and only supports deleting one after its ISU was removed from the app or the app was deleted.

If the app's endpoints need OAuth scopes the generated client doesn't have, a Developer Site user can open the client, click Edit API Client, select the scopes and save.

Check 3: the tenant is authorized on the API client

Development tenants are authorized for all your account's API clients automatically. Implementation, Sandbox and Production tenants are not. For each non-Development tenant, a Company Administrator must:

  1. Open Console > API Clients on the Developer Site.
  2. Select the API client for this app and this tenant (each tenant has its own).
  3. Click Modify Authorized Tenants, select the tenant, and click Save Changes.

It's easy to miss, because it happens on the Developer Site rather than in the tenant, and it needs Company Administrator access that the developer may not have.

After a refresh from Production

A refresh copies Production's ISU configuration into Implementation and Sandbox, and those tenants then use Production's API client. Workday's instruction is to add consent for each refreshed Implementation and Sandbox tenant to the Production API client. An app that worked in Sandbox until a refresh and fails straight after it fits this pattern. The Sandbox refresh guide lists the other items a refresh resets.

Check 4: the ISU can reach the data

If authentication succeeds but the call is refused or returns nothing, the problem is permissions, not configuration. Workday's ISU setup page asks for:

  • An Integration System Security Group (Unconstrained) containing the ISU.
  • View or Modify on the domains behind every Workday REST API the app calls. For Graph API, the domains of the query data sources and mutations used.
  • Get or Put on the domains of any SOAP operations called from orchestrations.
  • View or Modify on the app's own model security domains, if the endpoint reads or writes the app's business objects.
  • Activate Pending Security Policy Changes afterwards.

Each endpoint's description in the REST API Explorer on the Developer Site lists the domains that secure it, which is the quickest way to find what to grant. Workday's setup page also says to keep the ISU's session timeout at zero so the session doesn't expire.

Check 5: the SMD and PMD point at the same names

  • scheme is ISU, in upper case; Workday marks it case-sensitive.
  • username matches the ISU's account name exactly as assigned in App Manager.
  • Each endpoint's authType equals the id of the ISU entry, and the id is unique across your apps, not just this one.

A mismatch here fails in every tenant, which separates it from checks 1 to 3, which fail in one tenant while another works.

Places the simplified ISU doesn't work

Some failures come from using the scheme where Workday doesn't support it:

  • Custom Agent Action orchestrations. Workday says ISU credentials there cause a build failure. These actions run as the signed-in user.
  • App Preview. The documented list of authType values App Preview honours when connected to a tenant is AWSV4, NoAuth, OAuth client credentials, SSO and WCPISU. ISU isn't on it, so test ISU endpoints by deploying the app and running it in the tenant.
  • Trigger Business Process Step. It technically accepts an ISU credential, but Workday recommends access tokens there.
  • Studio integrations. Workday asks you not to reuse the simplified ISU API client; create a separate client with the client credentials grant.

How to prove it's fixed

Deploy the app to the tenant and open the page as a test user who can open the page but has no access to the underlying data. If the endpoint returns data, it authenticated as the ISU. Then run it in each tenant you promoted to, because each has its own assignment, client and consent. For orchestrations, run once and confirm the Send Workday API Request step succeeds in the run's logs.

Keep in mind Workday's security note: an ISU scheme is always a security exception, since the ISU's access doesn't follow the end user's. Secure the page with the app's own security domains, or check the user's roles in the app, before you ship it. The legacy WCPISU guide explains the older scheme if your app still has endpoints on it.

Sources checked