Fix Workday OAuth 2.0 handshake errors by isolating whether the failure occurs at the browser Authorization Endpoint (/<tenant>/authorize) or the server Token Endpoint (/ccx/oauth2/<tenant>/token), then checking the exact error code against your View API Clients record. Nearly every invalid_client, unauthorized_client, invalid_grant, and redirect_uri failure stems from a tenant-alias mismatch after Sandbox refresh, an unencoded or whitespace-padded Basic header, a trailing slash in the callback URI, or a PKCE S256 padding bug.
Master Diagnostic Table: Error -> Cause -> Repair -> Proof
Use this reference to map the exact JSON error code or browser failure directly to its root cause in Workday:
| Error Code / Symptom | Failing Endpoint | Root Cause in Workday or Client | Exact Repair | Verification Proof |
|---|---|---|---|---|
Error Code / Symptominvalid_client (401 / 400) |
Failing EndpointPOST /token |
Root Cause in Workday or ClientWrong Client ID or Client Secret; newline in Base64(id:secret); Client ID belongs to Sandbox while URL points to Implementation/Prod; API client disabled. |
Exact RepairCopy exact Token Endpoint and Client ID from View API Clients. If secret is uncertain, run Generate New API Client Secret. Strip trailing \n before Base64 encoding. |
Verification ProofPOST /token with a dummy code returns invalid_grant instead of invalid_client (proving client auth passed). |
Error Code / Symptomunauthorized_client (400) |
Failing Endpoint/authorize or /token |
Root Cause in Workday or ClientClient Grant Type does not permit the requested flow (e.g., sending grant_type=authorization_code to an ISU integration client, or grant_type=client_credentials to an Auth Code client). |
Exact RepairCheck client type (Register API Client vs. Integrations). Recreate or edit client with Authorization Code Grant. |
Verification Proof/authorize renders Workday sign-in or redirects cleanly to SAML IdP. |
Error Code / SymptomRedirect URI mismatch / invalid_request |
Failing EndpointGET /authorize or POST /token |
Root Cause in Workday or Clientredirect_uri differs by scheme (http vs https), port, case, or trailing / from Redirection URI on client; or redirect_uri omitted on /token after being sent on /authorize. |
Exact RepairRun Edit API Client and align Redirection URI character-for-character; pass the identical redirect_uri in both /authorize and /token. |
Verification ProofBrowser redirects (302 Found) back to callback URL with ?code=...&state=.... |
Error Code / Symptominvalid_grant (on authorization_code) |
Failing EndpointPOST /token |
Root Cause in Workday or ClientAuthorization code already redeemed once (duplicate callback/prefetch); code expired; PKCE code_verifier mismatch or Base64 +///= instead of Base64URL; wrong tenant alias in /token. |
Exact RepairEnsure single redemption; verify SHA-256 Base64URL without = padding; match /token tenant path to /authorize. |
Verification ProofPOST /token returns 200 OK with JSON Bearer payload. |
Error Code / Symptominvalid_grant (on refresh_token) |
Failing EndpointPOST /token |
Root Cause in Workday or ClientSuperseded refresh value used after rotation; Refresh Token Timeout (in days) elapsed; worker or ISU Workday Account disabled or renamed; Non-Expiring Refresh Tokens unchecked on ISU client. |
Exact RepairSerialize concurrent refreshes (see rotation guide); check worker account status; re-authorize via /authorize. |
Verification ProofSingle-threaded grant_type=refresh_token returns fresh access + refresh pair. |
| Error Code / SymptomHTTP 500 / Tenant Not Found | Failing EndpointGET /authorize |
Root Cause in Workday or ClientOAuth 2.0 Clients Enabled unchecked on Edit Tenant Setup - Security; invalid client_id string; UI host mixed up with services1 API host. |
Exact RepairEnable OAuth 2.0 Clients Enabled; use the exact Authorization Endpoint host from View API Clients (not the REST services host). |
Verification ProofNavigating to /authorize loads login prompt instead of error page. |
Repairing invalid_client and Basic Header Encoding Bugs
When exchanging an authorization code or refresh value at Workday’s /ccx/oauth2/<tenant>/token endpoint, confidential clients authenticate using [Client_ID]:[Client_Secret]. Three subtle formatting bugs trigger {"error": "invalid_client"}:
- Accidental space after the colon or trailing newline: Running
echo "id:secret" | base64in a shell appends a\nbyte (0x0a) into the Base64 payload. Always useprintf '%s:%s' "$CLIENT_ID" "$CLIENT_SECRET" | base64 | tr -d '\n'. - Tenant refresh overwrites: When Production refreshes Sandbox, any API client registered only in Sandbox prior to the refresh is wiped—or its Client ID and Secret now reflect Production’s client record while pointing to Sandbox’s tenant alias. Always re-verify View API Clients in Sandbox after a tenant refresh.
- Mixing UI and Services hostnames: Workday’s Authorization Endpoint uses the interactive web host, whereas the Token Endpoint uses the web-services host (
services1on standard tenants, orauth.api.workday.comon Extend API Gateway). Never hand-construct these URLs by guessing; copy both verbatim from View API Clients.
POST /ccx/oauth2/gms_preview/token HTTP/1.1
Host: wd3.workday-host.example
Authorization: Basic T0RRNFpEZGtOekl0TXpoaU1DMDBZbUZtCg==
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=88xr1xk2snm6u6pk5yc6yqef0POST /ccx/oauth2/gms/token HTTP/1.1
Host: services1.wd3.workday-host.example
Authorization: Basic T0RRNFpEZGtOekl0TXpoaU1DMDBZbUZt...
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=88xr1xk2snm6u6pk5yc6yqef0&redirect_uri=https%3A%2F%2Fportal.company.example%2Foauth%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkRepairing PKCE code_verifier and code_challenge Mismatches
When Support Proof Key for Code Exchange (PKCE) is enabled on Register API Client, Workday enforces RFC 7636 validation. If POST /token returns {"error": "invalid_grant"} on a brand-new authorization code, inspect your PKCE encoding:
- Standard Base64 instead of Base64URL: Standard Base64 outputs
+,/, and trailing=characters. If your app sends+unescaped in the/authorizequery string, HTTP URL decoding turns+into a space (0x20), corrupting the storedcode_challenge. Replace+with-, replace/with_, and strip all trailing=characters. - Missing
code_challenge_method=S256: Always passcode_challenge_method=S256explicitly on/authorize. If omitted, servers that default toplaincompare the rawcode_verifierdirectly against the SHA-256 hash and reject the exchange. - Browser link prefetchers or double React
useEffectmounts: Authorization codes are strictly single-use. In React development builds (StrictMode) or browsers/chat scanners that prefetch callback URLs, firing two/tokenrequests for the same?code=causes the second call to fail withinvalid_grant—and can revoke the grant issued to the first call. Guard your callback route so eachcodeis exchanged at most once.
Repairing redirect_uri Mismatches Across Environments
Workday validates redirect_uri twice: first before presenting the sign-in screen at /authorize, and second when validating the authorization_code at /token.
- Open View API Clients, locate your client on the API Clients tab, and open API Client > Edit API Client.
- Inspect every entry in Redirection URI:
- Confirm
https://is used (Workday requires HTTPS for external production callbacks). - Remove accidental query parameters (
?env=sandbox) from registered URIs; carry dynamic context inside the OAuthstateparameter instead. - Check reverse proxies and load balancers: if TLS terminates at an AWS ALB or Cloudflare proxy and forwards
http://internally to your Node or Python app, your OAuth library may auto-constructredirect_uri=http://...on the/tokenPOST while/authorizesenthttps://.... Pin the publichttps://callback URL explicitly in environment configuration or honorX-Forwarded-Proto: https.
- Confirm
Fast 4-Step Verification Checklist
- Confirm tenant toggle: Open Edit Tenant Setup - Security -> verify OAuth 2.0 Clients Enabled is checked.
- Diff
View API Clients: Confirm Client ID, Client Grant Type (Authorization Code Grant), PKCE check box, and Redirection URI match your app’s runtime config byte-for-byte. - Prove client credentials in isolation: Send a
POSTto the Token Endpoint withgrant_type=authorization_code&code=test_invalid_code. Receiving400 {"error": "invalid_grant"}proves your URL, TLS, Client ID, and Client Secret are 100% valid! Receiving401orinvalid_clientisolates the bug to your client credentials or endpoint host. - Trace end-to-end: Complete one clean sign-in following How to Configure User-Delegated OAuth 2.0 Authorization Code Grant in Workday and check Signons and Attempted Signons if the user’s SSO login fails mid-redirect.
Teams deploying Kiweely Bridge (coming next) or Kiweely Leaf (coming next) avoid manual callback, PKCE, and endpoint-host mismatches: Bridge’s AI admin agent validates the Sandbox Register API Client configuration, Functional Area scopes, and live role handshakes automatically before publishing the connector.
Frequently asked questions
Why does Workday return HTTP 500 Internal Server Error on the Authorize Endpoint?
On Workday's /authorize page, an HTTP 500 or generic error screen before sign-in usually means the client_id query parameter is malformed, belongs to a different tenant (such as Sandbox Preview instead of Sandbox), or OAuth 2.0 Clients Enabled is unchecked.
Does a trailing slash in redirect_uri really break Workday OAuth?
Yes. Workday compares the redirect_uri query and form parameter byte-for-byte against the Redirection URI registered on the API client. https://app.company.example/callback/ will not match https://app.company.example/callback.
Why does grant_type=authorization_code return invalid_grant on the very first attempt?
First-try invalid_grant errors come from four causes: PKCE code_verifier does not hash to the SHA-256 code_challenge sent on /authorize, redirect_uri in the /token POST differs from /authorize, the code expired (single-use, short TTL), or you posted to the wrong tenant's /token URL.
What causes invalid_client when the Client ID and Client Secret look right?
Check for trailing whitespace or newline characters before Base64-encoding Client_ID:Client_Secret, verify nobody regenerated the Client Secret in Workday, and confirm you aren't mixing a Sandbox Client ID with a Production Token Endpoint.