---
title: "Workday Session Timeouts and OAuth Token Lifetimes — Kiweely"
description: "How Maintain Password Rules session timeouts, OAuth API Client expiry checkboxes, refresh token days, and MFA settings interact for external web and mobile…"
url: https://kiweely.com/guides/workday-anonymous-vs-authenticated-session-timeout-oauth
---

# Aligning Workday Session Timeouts with External OAuth Access Token Lifetimes

By default, a Workday OAuth 2.0 access grant inherits the signed-in worker’s Workday session timeout from Maintain Password Rules or Edit Workday Account unless overridden on Register API Client, while Refresh Token Timeout (in days) sets an absolute re-authentication ceiling.

-   **Checked** against Workday on November 15
-   Applies to **Workday Authentication & Security**
-   6 min read
-   Published November 15
-   By Kiweely

In Workday, an external OAuth 2.0 access grant does not default to a fixed one-hour lifetime independent of the tenant—unless you explicitly check an access token expiry override on **Register API Client**, Workday ties the access grant’s timeout directly to the **Session Timeout Minutes** configured for that user on **Maintain Password Rules** or **Edit Workday Account**. Meanwhile, **Refresh Token Timeout (in days)** sets a non-sliding wall-clock ceiling measured from the original browser login, after which Workday forces full corporate SSO and MFA re-authentication.

When external web portals, mobile apps, or AI assistants drop employee connections every 15 minutes—or unexpectedly prompt for SSO in the middle of a workflow—the cause is almost always a mismatch between four separate timers inside Workday.

## The Four Timers Governing External Workday OAuth Sessions

Map every timeout control in your tenant before changing OAuth client settings, because shortening any single timer caps downstream sessions:

| Timer / Control | Where Configured in Workday | Scope | Exact Runtime Behavior |
| --- | --- | --- | --- |
|  **Tenant Default Session Timeout** |  **Maintain Password Rules** | All non-PCI Workday accounts without an account override | Sets inactivity timeout for UI sessions and baseline lifetime for user-delegated OAuth access grants. (PCI accounts are fixed at **15 minutes**.) |
|  **Individual Session Timeout Minutes** |  **Edit Workday Account** (or `SystemUsersForPurge` / `allWorkdayAccounts` audit) | Single worker or Integration System User | Overrides tenant default. ISUs default to `0` (unlimited) so batch runs do not expire mid-job; human accounts use positive minute values. |
|  **Enforce Customized Access Token Expiry** / **Enforce 60 Minute Access Token Expiry** |  **Register API Client** → **Expiry Time (In Minutes)** | Specific OAuth **API Client** | Overrides the user’s session timeout with a client-specific minute cap (for example, 15 minutes for a shared kiosk setup, or 60 minutes for strict external clients). |
|  **Refresh Token Timeout (in days)** |  **Register API Client** | Specific OAuth **API Client** | Absolute lifetime from the **first** `/authorize` login (for example, `30` days). Redeeming a refresh grant rotates the string but **never** extends this original deadline. |
|  **OTP Passcode Timeout (in minutes)** |  **Edit Tenant Setup - Security** → **Multifactor Authentication Settings** | Email / SMS One-Time Passcode MFA | Must be shorter than both tenant default and individual session timeouts (Workday warns that setting Passcode Timeout to 10 minutes requires user session timeouts **greater than 10 minutes**). |

For setting up the initial PKCE client registration, see [authenticating external tools with an OAuth API Client and PKCE](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password).

## Unauthenticated Sign-In Window vs. Authenticated Session Timeout

Administrators troubleshooting `401 Invalid Access Token` alongside SAML `AuthnRequest` failures often confuse two completely separate clocks:

1.  **The pre-authentication / sign-in handshake window:** While a user is still on the corporate Identity Provider screen completing SAML SSO or waiting for an emailed MFA code, no OAuth access grant exists yet. Two settings in **Edit Tenant Setup - Security** govern this phase:
    -   **SAML Clock Skew (`Additional Negative Skew` / `Additional Positive Skew`):** Workday enforces a combined **3-minute maximum** in either direction between the IdP’s `IssueInstant` and Workday server time.
    -   **MFA `Passcode Timeout (in minutes)`:** If a tenant sets an aggressive 10-minute user session timeout while also configuring a 10-minute Email or SMS One-Time Passcode timeout, the underlying pre-auth session expires before the worker finishes typing the code. Always keep tenant and individual session timeouts strictly above 10 minutes when OTP MFA is active.
2.  **The authenticated OAuth access window:** Once Workday redirects back to your `redirect_uri` with `code=...` and your client redeems it at `/ccx/oauth2/{tenant}/token`, Workday issues an `access_token` and (when configured) a `refresh_token`. From that point forward, API calls (`GET /workers`, WQL, RaaS, SOAP) validate the Bearer grant until either the client’s customized expiry elapses or the user’s Workday session timeout is reached.

## How Refresh Token Rotation Really Works in Workday

Many OAuth 2.0 client libraries assume “sliding refresh tokens”—meaning as long as an employee opens the app once a week, a 30-day refresh token lasts forever. **Workday does not extend refresh token deadlines on rotation.**

When your client exchanges a refresh grant after an `HTTP 401 Invalid Access Token`:

http

```
POST /ccx/oauth2/gms_dpt1/token HTTP/1.1
Host: wd5-services1.workday.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=ODQ4ZDdkNzItMzhiMC00YmFm
# plus the refresh_token form field holding the previously issued refresh string
```

Workday returns **both** a new `access_token` and a new `refresh_token`. Your client **must** overwrite its stored refresh string with the newly returned `refresh_token`, while keeping in mind three hard invalidation rules documented by Workday:

1.  **Fixed wall-clock horizon:** If **Refresh Token Timeout (in days)** on **Register API Client** is set to `30` days and the employee signed in on November 1, the refresh chain will fail with `invalid_grant` on December 1—even if the employee refreshed 50 times on November 30.
2.  **Account mutations revoke refresh grants immediately:** If the worker’s Workday username changes, an administrator locks the account, or the worker is terminated/deactivated, Workday invalidates all active refresh grants for that user immediately.
3.  **Never leave `Enforce 60 Minute Access Token Expiry` checked on tools that do not implement silent refresh:** Workday’s Studio MFA setup explicitly notes that checking **Enforce 60 Minute Access Token Expiry** cuts off OAuth 2.0 authentication after 60 minutes for clients that rely on session-bound grants. Enable customized minute expiry only when your external client handles `401` refresh rotation cleanly—or when you intentionally want a short-lived setup window, such as **Register API Clients for Time Kiosks**.

## Auditing Account-Level Timeout Overrides with WQL

If nine employees stay connected all morning while one finance manager gets `401 Invalid Access Token` every 15 minutes, check two user-specific overrides before touching your OAuth client:

1.  **PCI User Account status:** Workday hard-locks PCI user accounts to a **15-minute** session timeout; administrators cannot lengthen it.
2.  **Per-account `sessionTimeoutMinutes` override:** Someone previously edited that user via **Edit Workday Account** (or an inbound EIB) and set a custom timeout shorter than **Maintain Password Rules**.

You can audit per-account timeout overrides across your tenant using the `allWorkdayAccounts` WQL data source:

sql

```
SELECT workdayAccount, userName, sessionTimeoutMinutes, accountDisabled, accountLocked
FROM allWorkdayAccounts
WHERE sessionTimeoutMinutes > 0
ORDER BY sessionTimeoutMinutes ASC
LIMIT 100
```

Also watch WQL pagination caches when aligning timeouts: Workday caches paginated WQL query snapshots (`limit` and `offset`) only for the length of the active user session, **up to a maximum of 30 minutes** (see [paginating WQL results past 500 rows](https://kiweely.com/guides/wql-more-than-500-rows)). Keep access grant lifetimes at least 30 minutes if your application pages through multi-thousand-row WQL datasets.

## Mobile Biometrics, SSO Redirects, and External Employee Surfaces

On mobile devices, **Edit Tenant Setup - Security** separates Workday’s native app settings (**Enable Biometric Authentication**, **Enable Mobile PIN Authentication**, and **Max Mobile Authentication Age (in days)** from `30` to `365` days) from external OAuth clients. When **Always Require IdP Authentication** (`ForceAuthn`) is selected on your SAML Identity Provider row, every expired Refresh Token Window forces a full IdP challenge rather than silently reusing an existing browser SSO cookie.

External employee platforms that pass Workday permissions straight through rely on clean alignment between these timers. [Kiweely Leaf](https://kiweely.com/leaf) (coming next) pairs Workday OAuth 2.0 Authorization Code sign-in with device Face ID or fingerprint inside the Kiweely Leaf phone app while storing zero HR data at rest, and [Kiweely Bridge](https://kiweely.com/bridge) (coming next) seals each employee’s user-delegated OAuth grant with AES-256-GCM inside the client session so token rotation respects your tenant’s exact session and refresh policies without keeping a credential database.

## Configuration & Alignment Checklist

1.  Check **Maintain Password Rules** for your tenant’s baseline session timeout, and confirm it exceeds `10` minutes if Email or SMS OTP MFA is enabled on **Edit Tenant Setup - Security**.
2.  Query `allWorkdayAccounts` (or inspect **Edit Workday Account**) when a single worker experiences premature `401` expirations, and check whether the worker holds a 15-minute PCI role.
3.  On **Register API Client**, only enable **Enforce Customized Access Token Expiry** when your application implements automatic `grant_type=refresh_token` rotation and replaces both the access and refresh values on every refresh response.
4.  Set **Refresh Token Timeout (in days)** to match your corporate SSO re-authentication policy (for example, `7`, `14`, or `30` days), and code your UI to redirect cleanly to `/authorize` on `invalid_grant` when that fixed horizon expires.
5.  Verify **SAML Setup** → **Always Require IdP Authentication** matches whether you want employees to re-enter IdP credentials or quietly bounce through an active SSO session after refresh expiration.

## Frequently asked questions

### Where do you set the default Workday session timeout for employees?

Run the Maintain Password Rules task to configure the tenant-wide default session timeout for non-PCI accounts, or run Edit Workday Account to override Session Timeout Minutes on an individual account. PCI user accounts are locked by Workday to a 15-minute session timeout and cannot be extended.

### Does redeeming a Workday refresh token extend the Refresh Token Timeout window?

No. Although calling the token endpoint with grant\_type=refresh\_token returns both a fresh access grant and a rotated refresh grant, the Refresh Token Timeout (in days) clock starts at the initial browser authorization and never slides forward. Once that day count elapses, the user must sign in again via the authorize endpoint.

### Why does checking Enforce 60 Minute Access Token Expiry break Workday Studio OAuth sessions?

Workday's Studio MFA documentation explicitly warns against selecting Enforce 60 Minute Access Token Expiry on Studio API Clients because Studio stops authenticating OAuth calls once that 60-minute cutoff passes rather than silently cycling grants mid-deployment.

### How does session timeout affect paginated WQL queries over OAuth?

Workday caches WQL pagination result sets only for the duration of the active user session, up to a hard maximum of 30 minutes. If the user's OAuth session times out mid-export, subsequent offset calls fail or recompute against live data.

## Sources checked

-   [Concept: Session Timeout](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/navigation/kat1386284737608.html)
-   [Reference: Edit Tenant Setup - Security](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/tenant-setup/dan1370796470031.html)
-   [Enable Multifactor Authentication in Workday Studio](https://doc.workday.com/admin-guide/en-us/workday-studio/integration-deployment/multifactor-authentication-in-workday-studio/kuh1623937418623.html)
-   [Request a New Access Token with a Refresh Token](https://developer.workday.com/documentation/cqa1553122177664)
-   [Register API Clients for Time Kiosks](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/time-entry-setup/time-kiosk/register-api-clients-for-time-kiosks.html)

## Related guides

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

-   [### How to Authenticate Workday Studio and External Tools Using an OAuth API Client with PKCE (When SSO Blocks Passwords) When SSO leaves consultants without a Workday password, register an API Client with Authorization Code Grant and Support Proof Key for Code Exchange enabled, then use that client ID with Studio or Vine OAuth sign-in instead of username and password auth.](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password)
-   [### 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.](https://kiweely.com/guides/workday-isu-authentication-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 get more than 500 rows from a Workday WQL query? The 500-row stop belongs to the View WQL Query Result report. The WQL REST API returns up to 10,000 rows per page: pass limit (0 to 10,000) and offset. A worked run pages 48,491 rows in five calls, with Workday’s exact errors for a limit above 10,000 and an offset past the end.](https://kiweely.com/guides/wql-more-than-500-rows)

### More guides on Business processes and security

[All 27 guides](https://kiweely.com/guides#business-processes)

-   [How Workday Terminations and Job Transfers Affect Active OAuth Grants](https://kiweely.com/guides/workday-revoke-oauth-tokens-terminated-transferred-workers)
-   [Configuring Workday Pre-Hire Security So New Employees Can Complete Tasks Before Day One](https://kiweely.com/guides/workday-pre-hire-onboarding-access-before-day-one-security)
-   [Tuning Workday Business Process Notifications When Using External Mobile or Chat Approvals](https://kiweely.com/guides/workday-notification-delivery-settings-suppressing-duplicate-emails)
-   [Workday Time Off vs. Leave of Absence: Helping Employees Pick the Right Request Type](https://kiweely.com/guides/workday-leave-of-absence-vs-time-off-employee-request-routing)
-   [How to Trace Who Approves a Leave or Expense Request in a Workday Supervisory Org](https://kiweely.com/guides/workday-find-approver-chain-supervisory-org-business-process)
-   [Validating Country-Specific Address and Emergency Contact Formats in Workday Self-Service](https://kiweely.com/guides/workday-emergency-contact-home-address-change-validation-rules)
-   [How Workday Task Delegation Works When Managers Approve Through APIs](https://kiweely.com/guides/workday-delegation-rules-external-approvals-acting-on-behalf)
-   [Why Workday Says ‘This Task Is Not Available’ or ‘Waiting on Initiator’ on a Business Process Step](https://kiweely.com/guides/workday-business-process-this-task-is-not-available)

### From the blog on Business processes and security

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

-   [Why Copy-Pasting Workday Data into Consumer Chatbots Risks Client Data (and How Zero-Retention AI Fixes It)](https://kiweely.com/blog/workday-client-data-privacy-zero-retention-ai)
-   [Why Workday Business Processes Stall: The 5 Most Overlooked Routing Glitches](https://kiweely.com/blog/why-workday-business-processes-stall)
-   [Keeping External Workday Screens in Sync When You Change Absence Plans or Approval Rules](https://kiweely.com/blog/updating-custom-workday-screens-when-business-processes-change)

## 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.
