---
title: "Workday ISU or API client 401, invalid_client, invalid_grant"
description: "Why a Workday ISU or API client throws 401, invalid_client, or invalid_grant, and whether the real cause is the ISU, its security group, or the client."
url: https://kiweely.com/guides/workday-isu-authentication-errors
---

# Workday ISU or API client 401, invalid\_client, invalid\_grant

These errors usually blame the token, but the real cause is the ISU’s own account, its security group’s activation, or the wrong client task — not a corrupted credential.

-   **Checked** against Workday on September 25
-   Applies to **Workday integrations**
-   6 min read
-   Published September 25
-   By Kiweely

## Work out which layer is actually failing first

A Workday integration or API client fails authentication for one of three separable reasons: the integration system user (ISU) account itself is blocked, its security group doesn’t reach the domains the call needs, or the API client credential (its ID, secret, or refresh token) is wrong or expired. The error text points at one of these, but the same message can have more than one real cause underneath it. This guide assumes the ISU and API client already exist — [setting up a Workday integration system user and API client](https://kiweely.com/guides/workday-integration-system-user-api-client) covers creating them in the right order; this is what to check once that setup stops working.

Workday error

## “401 Unauthorized”

Workday’s own REST API reference gives this one two distinct meanings. Plain **401 Unauthorized** means valid credentials weren’t supplied at all — check that the `Authorization` header is actually present and well-formed on the request that’s failing, not just on the ones you tested by hand. A separate message, **Invalid Access Token**, means the bearer token itself isn’t valid or has expired; request a fresh access token from the token endpoint rather than reusing an old one.

An access token issued by Workday is short-lived by design. If a scheduled job caches a token and calls it hours later, this is the expected result — the fix is to request a new access token before each run, or when the previous one is close to expiring, not to treat a fresh token as something to conserve.

Workday error

## invalid\_client

The token endpoint couldn’t match the client ID and secret you sent to a registered API client. The usual cause is mechanical: a truncated copy-paste of the secret, a client ID from a different API client (an interactive client’s ID used where an integrations client’s ID belongs), or credentials copied from a different tenant. If you’ve lost the secret, generate a new one from the client’s record rather than guessing at the old one — Workday only displays a secret once, at creation.

Workday error

## invalid\_grant

This means the token endpoint accepted the client ID and secret but rejected the grant itself — almost always the refresh token. Workday documents refresh tokens as tied to the specific account that authorized them: if the ISU’s username changes, or the ISU is deactivated, the refresh token issued under it stops working, even though nothing about the API client changed. A refresh token regenerated for a different client ID than the one in the request fails the same way. When a previously working integration starts throwing `invalid_grant` with no change on your side, check the ISU’s own state before touching the client: a changed password, a security group change, or a deactivated account is the more common cause than a corrupted token value.

If the client uses **Non-Expiring Refresh Tokens**, the refresh token itself has no expiry — an `invalid_grant` on that kind of client points even more strongly at the ISU or at a token that was regenerated (and the old one invalidated) rather than at natural expiry.

## The ISU’s own account: password expiry and UI sessions

An ISU is a Workday user account, and by default it’s subject to the tenant’s password expiration policy exactly like a person’s account — until you add it to the **System Users Exempt from Password Expiration** field on the Maintain Password Rules task. Without that, the ISU’s password eventually expires on its own schedule, and every call using it starts failing for a reason that has nothing to do with the API client, the refresh token, or the security group.

**Do Not Allow UI Sessions** should be selected on the ISU, which removes its ability to sign in through a browser at all — this doesn’t cause the failures above, but if it’s ever unchecked while diagnosing something else, put it back before you move on, since an ISU exists to answer API calls, not to hold an interactive session.

## Security group membership and domain permissions, both — and activation

Three separate things have to be true for the ISU to reach a given call, and a 403, or a functional 401-shaped failure that isn’t really about the token, usually traces to one of them:

-   The ISU must be a member of an integration system security group. Membership changes take effect immediately.
-   That group must have the right permission on the domain the call needs — **Report/Task Permissions** (View for reads, Modify for writes) for REST calls, or **Integration Permissions** (Get for reads, Put for writes) for SOAP. Workday’s own REST API security reference is explicit that REST calls need Report/Task Permissions whether the caller is an ISU or a person; Integration Permissions apply to SOAP only, so a group with only Get and Put still fails a REST call.
-   Any change to a domain security policy — adding the group, or changing its permission level — stays **pending** until someone runs **Activate Pending Security Policy Changes**. Unlike a group membership change, a policy edit has no effect at all until that task runs. “The security is definitely set up right” and a 403 anyway is, more often than not, this step skipped.

## Register API Client for Integrations vs. Register API Client

Workday has two separate client-registration tasks, and using the wrong one produces exactly the authentication errors above with no obvious reason why. **Register API Client for Integrations** is for a service that runs unattended: it supports **Non-Expiring Refresh Tokens** and a **Scope (Functional Areas)** setting that should cover only the functional areas the integration actually calls, not every area by default. The plain **Register API Client** task is built for an interactive flow with a real person completing a browser authorization step — a grant type meant for a user-facing app, not a background job. Registering a service account under the interactive task, or vice versa, is an avoidable source of `invalid_client` and `invalid_grant` once the client is actually put to use.

A client’s scope has a related consequence: functional areas outside what was granted at registration aren’t something you can fix by requesting a new token — the client itself has to be reconfigured, and, for a domain permission change on top of that, activated.

## The wrong tenant or endpoint in the token request

The token request goes to a URL shaped like `https://{host or gateway}/ccx/oauth2/{tenant}/token` — both the host and the tenant name are specific to your tenant, not a generic Workday address. A request built against a different tenant’s name, or against credentials copied from one tenant into another (a common mistake right after a Sandbox refresh), fails authentication even though the client ID and secret are individually valid, because they were never valid together with that tenant.

```
POST https://<host or gateway>/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>
```

If you’ve recently changed which tenant you’re pointing at — moved from Sandbox to Production, or picked up a refreshed tenant — confirm the tenant name in the URL before re-checking the client or the ISU; it’s the fastest thing to get wrong and the easiest to overlook once the credentials themselves look right.

## Prove it with the same request that’s failing, isolated

Once you’ve made a change, re-run the exact failing request in isolation — the token exchange by itself, then a single small read — rather than restarting the full integration and hoping. A 200 on the token exchange isolates the client and the ISU from everything downstream; a 200 on the read after that confirms the security group and activation are both in place. For the ordered setup this guide assumes is already done, see [setting up a Workday integration system user and API client](https://kiweely.com/guides/workday-integration-system-user-api-client). If the credential in question drives a Workday Extend orchestration rather than an external client, see [Orchestrate errors and what they mean](https://kiweely.com/guides/orchestrate-errors) for the separate credential-type failure that shows up there instead.

If the failure is a person, not the ISU, who can’t start the integration, the permission question is different: see [who can launch a specific Workday integration](https://kiweely.com/guides/workday-who-can-launch-integration).

## Sources checked

-   [Reference: REST API Error Messages](https://developer.workday.com/documentation/GUID-6f06b090-c7b5-47cc-b929-d2a1f1116eef-enHYPHENus/ReferenceRESTAPIErrorMessages)
-   [Request a New Access Token with a Refresh Token](https://developer.workday.com/documentation/cqa1553122177664/RequestaNewAccessTokenwithaRefreshToken)
-   [Concept: Workday REST API Security](https://developer.workday.com/documentation/dan1370797986071/ConceptWorkdayRESTAPISecurity)
-   [Register API Client for Data Lake (Refresh Token Grant)](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/register-api-client-for-data-lake--refresh-token-g.html)
-   [Security Policy Configuration and Activation](https://doc.workday.com/workday-education/en-us/course-manuals/security-for-administrators/security-policy-configuration-and-activation.html)
-   [Advanced Security Group Types](https://doc.workday.com/workday-education/en-us/course-manuals/hcm-core-supplemental-for-administrators/advanced-security-group-types.html)
-   [Make Adaptive Planning API Requests with Workday Credentials (token endpoint format)](https://doc.workday.com/adaptive-planning/en-us/workday-adaptive-planning-documentation/integration/managing-data-integration/api-documentation/understanding-the-adaptive-planning-rest-api/bit1623710301264.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### Why did my Workday EIB load fail? Fix Invalid ID Value and field restriction errors Open the integration event on View Background Process. For Completed With Errors, select Number of Errors to read each row’s message. Invalid ID Value is a wrong Reference ID; ‘does not meet the restrictions’ names the field, and in Workday’s example the launching user lacked security for it.](https://kiweely.com/guides/workday-eib-load-errors)
-   [### How do I set up an integration system user and API client in Workday so an external app can authenticate? Create the ISU, put it in an Integration System Security Group, grant domain permissions and activate them, register the client for integrations, then generate its refresh token and pick the ISU as the Workday account.](https://kiweely.com/guides/workday-integration-system-user-api-client)
-   [### How do I debug a Workday Orchestrate orchestration that shows success but some steps failed? A run can look successful because an unsuccessful HTTP response is not a failure unless a retry policy defines a success range, and an error handler set to Conditional Outputs lets the run carry on. Read the run’s per-process stepsFailed, not the status.](https://kiweely.com/guides/orchestrate-errors)

### More guides on Integrations and APIs

[All 89 guides](https://kiweely.com/guides#integrations)

-   [What is the safest way to copy Workday configuration from one tenant to another?](https://kiweely.com/guides/workday-configuration-between-tenants)
-   [Multi-Tenant FDE Access via Customer Central Manage Tenant Access](https://kiweely.com/guides/multi-tenant-fde-customer-central-access)
-   [Configuration Catalog migrate blocked: fix the first 50 Object Transporter prerequisites](https://kiweely.com/guides/configuration-catalog-prerequisites-blocking)
-   [Why the same account ID across tenants unlocks Object Transporter](https://kiweely.com/guides/workday-customer-central-same-account-id)
-   [Tenant Compare after Object Transporter: when and how to run it](https://kiweely.com/guides/workday-tenant-compare-after-migration)
-   [How to find what Object Transporter can migrate](https://kiweely.com/guides/workday-object-transporter-supported-objects)
-   [Permission to launch a Workday integration: which domains Studio checks](https://kiweely.com/guides/permission-to-launch-workday-integration)
-   [What Workday Customer Central is (and isn’t) for implementers](https://kiweely.com/guides/workday-customer-central-for-implementers)

### From the blog on Integrations and APIs

[All posts](https://kiweely.com/blog)

-   [How to Reconcile Workday Payroll Feeds in Studio Without Days of Manual XML Diffs](https://kiweely.com/blog/reconciling-workday-payroll-studio-feeds-with-ai)
-   [Turning a Messy Client Spreadsheet into a Clean Workday EIB Load in One Conversation](https://kiweely.com/blog/messy-spreadsheet-to-workday-eib-load-with-ai)
-   [Workday REST API vs. SOAP Web Services: Why Setup Work Still Needs the Task Screen](https://kiweely.com/blog/workday-rest-api-vs-soap-coverage-gaps)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
