Skip to content
KiweelyKiweelyKiweely

Managing Workday OAuth Refresh Token Expiration, Rotation, and Revocation

Workday rotates user-delegated OAuth refresh tokens on every exchange while enforcing a fixed absolute Refresh Token Timeout measured from initial sign-in. Learn how access TTLs, Enforce 60 Minute Access Token Expiry, and admin revocation tasks work.

  • Checked against Workday on
  • Applies to Workday Authentication & OAuth
  • 5 min read
  • Published
  • By Kiweely
On this page

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:

Works
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:

Works
{
  "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:

  1. All four requests receive 401 Unauthorized.
  2. Without synchronization, four worker threads simultaneously send grant_type=refresh_token with the same refresh string R1.
  3. Request 1 wins, receives new pair (A2, R2), and invalidates R1.
  4. Requests 2, 3, and 4 arrive milliseconds later with R1 and fail with 400 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): Choose 14 to 30 days 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 in HttpOnly, Secure encrypted server cookies or sealed client envelopes.
  • Distinguish rotation races from true expiry: Log whether an invalid_grant error 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.

Sources checked

Related guides

All guides

Let Workday check the work.

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

Get the next guide in your inbox.

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

We’ll email you once to confirm. Unsubscribe in one click from any issue.