Workday user-delegated OAuth 2.0 clients issue short-lived Bearer access credentials tied to tenant session timeouts and rotate refresh credentials on every grant_type=refresh_token call—while enforcing a non-sliding absolute ceiling set by Refresh Token Timeout (in days) from the moment the worker first signed in. By contrast, integration clients registered via Register API Client for Integrations support Non-Expiring Refresh Tokens managed manually by administrators.
Misunderstanding fixed-window refresh lifetimes, concurrent rotation races, or the Enforce 60 Minute Access Token Expiry check box causes surprise mid-day logouts across external portals, BI tools, and desktop integrations.
Lifecycle Comparison: User-Delegated vs. Integration Tokens
Token expiration and rotation behave differently depending on which registration task created the client (see full task comparison):
| Lifecycle Property | User-Delegated (Register API Client) |
Integration (Register API Client for Integrations) |
|---|---|---|
| Lifecycle PropertyAccess Credential Lifetime | User-Delegated ( Register API Client )Bound to the worker’s Workday session timeout (or 60 minutes on Extend API Gateway / custom expiry setting) | Integration ( Register API Client for Integrations )Short-lived Bearer access credential (typically tied to tenant/gateway TTL), renewed via refresh grant |
| Lifecycle PropertyRefresh Issuance | User-Delegated ( Register API Client )Returned automatically from /token after authorization_code redemption |
Integration ( Register API Client for Integrations )Generated manually in UI via API Client > Manage Refresh Tokens for Integrations |
| Lifecycle PropertyRefresh Rotation on Use | User-Delegated ( Register API Client )Yes: Every grant_type=refresh_token response returns both a new access credential and a new refresh value |
Integration ( Register API Client for Integrations )No (when Non-Expiring Refresh Tokens is selected, the same refresh value is reused across exchanges) |
| Lifecycle PropertyAbsolute Refresh Horizon | User-Delegated ( Register API Client )Fixed window: Refresh Token Timeout (in days) counts from initial browser sign-in and does not extend on refresh |
Integration ( Register API Client for Integrations )Indefinite when Non-Expiring Refresh Tokens is checked, until revoked or regenerated |
| Lifecycle PropertyEffect of Account Deactivation | User-Delegated ( Register API Client )Immediately invalidates refresh and blocks new access issuance | Integration ( Register API Client for Integrations )Fails with invalid_grant if the bound ISU account is disabled or its username changes |
Why Enforce 60 Minute Access Token Expiry Breaks Interactive Sessions
When configuring Register API Client, administrators often see Enforce 60 Minute Access Token Expiry (or Enforce Customized Access Token Expiry on specialized setups such as Time Kiosks) and assume checking it is a harmless security hardening step.
In Workday’s OAuth implementation, Workday explicitly warns in its Studio and external client setup documentation not to select Enforce 60 Minute Access Token Expiry for standard ongoing interactive sessions because doing so disables OAuth 2.0 authentication continuity after that 60-minute window rather than merely triggering silent background refreshes. Standard Workday OAuth 2.0 access credentials already obey the normal Workday session timeouts configured tenant-wide (on Edit Tenant Setup - System / Security) or per account.
Reserve customized minute-level access expiry strictly for ephemeral provisioning flows—such as a manager registering a physical Workday Time Kiosk device where the setup credential should self-destruct minutes after pairing.
Executing a Token Refresh Safely (Rotation & Concurrency)
When a user-delegated Bearer credential expires (returning 401 Unauthorized on a REST, WQL, or RaaS request), exchange the current refresh credential at your tenant’s Token Endpoint:
POST /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=refresh_token&client_id=ODQ4ZDdkNzItMzhiMC00YmFmLTgyNzAtNzljNjM0MDlmNmY2(Include the URL-encoded refresh_token form field carrying the latest refresh value received from Workday.)
Workday responds with a new Bearer credential and a new refresh credential:
{
"access_token": "28tyw9mpe7huyyah7gftg4djg",
"refresh_token": "1fndsc9ezoe4s4rbwrzzobgzw7l3os123o0qn1wckmf7zfv5o9v9r5l",
"token_type": "Bearer"
}Preventing Race Conditions on Parallel API Calls
Suppose an external dashboard fires four parallel Workday REST requests (workers/me, timeOffBalances, paySlips, supervisoryOrganizations) right after the access credential expires:
- All four requests receive
401 Unauthorized. - Without synchronization, four worker threads simultaneously send
grant_type=refresh_tokenwith the same refresh stringR1. - Request 1 wins, receives new pair
(A2, R2), and invalidatesR1. - Requests 2, 3, and 4 arrive milliseconds later with
R1and fail with400 Bad Request({"error": "invalid_grant"}), causing naive error handlers to wipe the user’s session!
Engineering fix: Wrap grant_type=refresh_token calls in a per-user single-flight lock (in-process promise deduplication for single-node apps, or a short Redis/mutex lock for multi-node backends) and atomically persist (A2, R2) before releasing waiting requests. Remember too that once the client’s Refresh Token Timeout (in days) elapses from the original sign-in timestamp, grant_type=refresh_token will legitimately return invalid_grant—at which point your app must redirect the user back to the Authorize Endpoint.
Administrative Inspection and Revocation Tasks
Security administrators control active OAuth credentials from the View API Clients report (secured to the Security Administration domain in the System functional area):
| Scenario | Exact Workday Navigation & Task | Immediate Effect |
|---|---|---|
| ScenarioRevoke one user’s or client’s refresh grants | Exact Workday Navigation & TaskView API Clients -> API Clients tab -> Related Actions on client -> API Client > Manage Refresh Tokens |
Immediate EffectRevokes selected refresh grants so no further access credentials can be minted |
| ScenarioRotate or revoke an integration ISU refresh grant | Exact Workday Navigation & TaskView API Clients -> API Clients for Integrations tab -> Related Actions -> API Client > Manage Refresh Tokens for Integrations |
Immediate EffectRegenerates or deletes the refresh credential bound to that Integration System User |
| ScenarioEmergency shutoff of an external app | Exact Workday Navigation & TaskView API Clients -> Related Actions -> API Client > Edit API Client (disable client or run Generate New API Client Secret) |
Immediate EffectBlocks all /authorize and /token exchanges for that client across the tenant |
| ScenarioOffboard a terminated worker | Exact Workday Navigation & TaskDisable Workday Account (Edit Workday Account or automated termination step; see termination lifecycle guide) |
Immediate EffectInvalidates all refresh grants tied to that user and blocks API execution |
Production Hygiene Checklist
- Set realistic
Refresh Token Timeout (in days): Choose14to30days for workforce tools so active employees aren’t forced through browser SSO every morning, while idle grants still age out predictably. - Never store plaintext Workday refresh grants in browser
localStorage: Keep credentials inHttpOnly,Secureencrypted server cookies or sealed client envelopes. - Distinguish rotation races from true expiry: Log whether an
invalid_granterror occurred within milliseconds of a sibling refresh exchange vs. after the configured timeout window (see Fixing Workday OAuth Errors).
In Kiweely Bridge (coming next), employee Workday OAuth grants are never stored in a central database table at rest: each user-delegated grant is sealed with AES-256-GCM and decrypted strictly in memory during an active call, giving employees and Workday admins instant revocation control without lingering third-party credential stores.
Frequently asked questions
Does exchanging a Workday refresh token extend the overall Refresh Token Timeout?
No. On user-delegated API clients, the Refresh Token Timeout (in days) starts at the initial browser authorization and never slides forward. Even if your app refreshes hourly, the user must re-authenticate at the Authorize Endpoint once that fixed window elapses.
Why did our OAuth sessions break exactly 60 minutes after sign-in?
An administrator likely checked Enforce 60 Minute Access Token Expiry (or Enforce Customized Access Token Expiry) on Register API Client, or your tenant's user session timeout expired without the client executing a refresh_token grant.
What happens if two concurrent worker threads try to use the same refresh token?
Because Workday rotates user-delegated refresh values upon exchange, the second concurrent POST with the superseded refresh value fails with invalid_grant. Serialize refresh calls per user session with a distributed lock or single-flight mutex.
How do I immediately revoke all active OAuth tokens for a compromised API client?
Open View API Clients, use the related actions menu on the API client to access Manage Refresh Tokens (or regenerate/disable the API client via Edit API Client), which immediately invalidates downstream refreshes.