---
title: "Configure Workday OAuth 2.0 Authorization Code Grant"
description: "Step-by-step setup of Workday Register API Client with Authorization Code Grant, PKCE S256, Bearer access credentials, Redirect URIs, and Functional Area…"
url: https://kiweely.com/guides/workday-authorization-code-grant-user-delegated-oauth-setup
---

# How to Configure User-Delegated OAuth 2.0 Authorization Code Grant in Workday

Register a user-delegated Workday OAuth 2.0 client using Register API Client with Authorization Code Grant, PKCE (S256), and Bearer credentials so external applications authenticate employees through SSO and run under their own Workday permissions.

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

Configure user-delegated OAuth 2.0 in Workday by enabling OAuth clients on **Edit Tenant Setup - Security**, running the **Register API Client** task with **Authorization Code Grant** and **Support Proof Key for Code Exchange (PKCE)** selected, and assigning the exact **Scope (Functional Areas)** your endpoints require. Every employee who signs in through the resulting **Authorization Endpoint** receives a short-lived Bearer credential scoped strictly to their own Workday security groups.

Unlike integration clients bound to an Integration System User ([compared in detail here](https://kiweely.com/guides/workday-register-api-client-vs-api-client-for-integrations)), user-delegated Authorization Code Grant preserves SAML SSO, multifactor authentication, row-level supervisory organization boundaries, and per-worker audit logging.

## Step 1: Verify Security Prerequisites and Tenant Setup

Before opening **Register API Client**, confirm that your administrative account belongs to a security group with `Modify` permission on both **Set Up: Tenant Setup - Security** and **Security Administration** in the **System** functional area.

1.  Run the **Edit Tenant Setup - Security** task.
2.  Expand the **OAuth 2.0 Settings** section.
3.  Confirm the **OAuth 2.0 Clients Enabled** check box is selected. If it is cleared, Workday rejects every `/authorize` and `/token` handshake across the tenant.
4.  Click **OK** to save any changes.

## Step 2: Run the Register API Client Task

Search for and open **Register API Client** (do not select *Register API Client for Integrations*). Complete the registration fields using the settings below:

| Field on Register API Client | Recommended Setting | Operational Impact |
| --- | --- | --- |
|  **Client Name** | Descriptive app and environment name (e.g., `Employee Portal - Sandbox`) | Appears in **View API Clients** and administrative audit trails |
|  **Client Grant Type** | `Authorization Code Grant` | Issues single-use authorization codes after interactive worker sign-in |
|  **Support Proof Key for Code Exchange (PKCE)** | Checked | Requires `code_challenge` (`S256`) on `/authorize` and `code_verifier` on `/token` |
|  **Access Token Type** | `Bearer` | Standard RFC 6750 HTTP `Authorization: Bearer` header format |
|  **Redirection URI** | Exact HTTPS callback URL (e.g., `https://portal.company.example/oauth/callback`) | Workday enforces character-for-character matching on scheme, host, port, and path |
|  **Enforce 60 Minute Access Token Expiry** | Leave **unchecked** unless explicitly required | Checking this disables ongoing OAuth refresh flows after 60 minutes in several interactive clients |
|  **Refresh Token Timeout (in days)** | Default (e.g., `30` or `90` days per corporate policy) | Absolute lifetime of the refresh chain measured from initial browser authorization |
|  **Scope (Functional Areas)** | Minimum required functional areas (e.g., `Staffing`, `Time Off and Leave`, `System`) | Acts as a ceiling; endpoints outside selected functional areas fail with `403` |
|  **Include Workday Owned Scope** | Checked | Grants client-level eligibility for core Workday platform domains not tied to a single functional area |

Click **OK**. Workday generates and displays four critical values on the confirmation screen:

-   **Client ID**
-   **Client Secret** (copy immediately into your secrets manager; Workday will not display the raw secret again)
-   **Workday REST API Endpoint** (`https://<services-host>/ccx/api/v1/<tenant>`)
-   **Token Endpoint** (`https://<services-host>/ccx/oauth2/<tenant>/token`) and **Authorization Endpoint** (`https://<ui-host>/<tenant>/authorize`)

Finding Endpoints Later

You can view the **Client ID**, **Workday REST API Endpoint**, **Token Endpoint**, and **Authorization Endpoint** anytime by running the **View API Clients** report and inspecting the **API Clients** tab.

## Step 3: Construct the PKCE Code Verifier and Authorization URL

When PKCE is enabled on the client, your application generates a fresh secret per sign-in attempt before opening the browser:

1.  **Generate `code_verifier`:** Create a cryptographically random URL-safe string between 43 and 128 characters (`A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, `~`).
2.  **Compute `code_challenge`:** Hash the ASCII bytes of `code_verifier` with SHA-256 and encode the digest using Base64URL without `=` padding.
3.  **Generate `state`:** Create an unpredictable random nonce tied to the user’s browser cookie or local session to prevent cross-site request forgery (CSRF).

Redirect the employee’s browser to your tenant’s **Authorization Endpoint**:

Works

```
GET /gms/authorize?response_type=code&client_id=ODQ4ZDdkNzItMzhiMC00YmFmLTgyNzAtNzljNjM0MDlmNmY2&redirect_uri=https%3A%2F%2Fportal.company.example%2Foauth%2Fcallback&state=9f8e7d6c5b4a&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 HTTP/1.1
Host: wd3.workday-host.example
```

Workday authenticates the worker according to your **Manage Authentication Policies** rules (redirecting to SAML SSO if configured, or prompting for Workday credentials and MFA). Once authenticated, Workday redirects the browser back to your **Redirection URI** with `code` and `state`:

Works

```
HTTP/1.1 302 Found
Location: https://portal.company.example/oauth/callback?code=88xr1xk2snm6u6pk5yc6yqef0&state=9f8e7d6c5b4a
```

Verify that the returned `state` matches the nonce stored before redirect; reject any mismatch immediately.

## Step 4: Exchange the Authorization Code at the Token Endpoint

Your backend (or native public client) exchanges the single-use `code` and original `code_verifier` via an `application/x-www-form-urlencoded` POST request to the tenant’s **Token Endpoint**.

For confidential clients issued a Client Secret, pass HTTP Basic authentication (`Base64(Client_ID:Client_Secret)`) or include the client credentials in the form body as required by your endpoint gateway:

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=authorization_code&code=88xr1xk2snm6u6pk5yc6yqef0&redirect_uri=https%3A%2F%2Fportal.company.example%2Foauth%2Fcallback&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
```

Workday hashes `code_verifier` with SHA-256, compares it against the stored `code_challenge`, and returns a JSON payload containing the short-lived Bearer credential and a rotating refresh value. If you hit `invalid_client`, `invalid_grant`, or callback mismatches during this step, walk through the diagnostic table in [Fixing Workday OAuth invalid\_client, unauthorized\_client, and Redirect URI Errors](https://kiweely.com/guides/workday-oauth-invalid-client-unauthorized-client-redirect-uri).

## Step 5: Test User-Delegated API Execution

Test the issued Bearer credential against a low-privilege endpoint such as `common/v1/workers/me` or a simple WQL query to prove both client scope and user security policies are aligned:

Works

```
GET /ccx/api/v1/gms/common/v1/workers/me HTTP/1.1
Host: services1.wd3.workday-host.example
Authorization: Bearer 7c3obrknwd6nnkxv0r64jdpbx
Accept: application/json
```

### Verification Checklist Before Production Cutover

-   **Test with a standard employee account, not an admin:** Sign in as a non-privileged worker (only `Employee As Self`) and verify they can read their own worker profile while receiving `403 Forbidden` or zero rows when querying another worker ID.
-   **Confirm Report/Task domain permissions:** Remember that Workday REST and WQL endpoints check **Report/Task Permissions** (`View` for GET, `Modify` for POST/PUT/PATCH/DELETE) on domain security policies—not *Integration Permissions* (`Get`/`Put`), which apply only to SOAP web services.
-   **Check Scope ceiling:** Review [Scoping Workday API Client Functional Areas for Least-Privilege Access](https://kiweely.com/guides/workday-api-client-functional-areas-least-privilege-scoping) to strip unused Functional Areas before migrating configuration to Production.
-   **Validate refresh behavior:** Confirm your client stores the new refresh value returned on every `grant_type=refresh_token` exchange, as detailed in [Managing Workday OAuth Refresh Token Expiration, Rotation, and Revocation](https://kiweely.com/guides/workday-oauth-refresh-token-expiration-rotation-revocation).

If you want to skip manual OAuth plumbing when exposing Workday to AI assistants or custom employee portals, [Kiweely Bridge](https://kiweely.com/bridge) (coming next, with an AI admin agent that guides `Register API Client` setup in Sandbox) and [Kiweely Leaf](https://kiweely.com/leaf) (coming next for external employee screens without an Extend license) run natively on this exact Authorization Code Grant + PKCE flow.

## Frequently asked questions

### Where do I copy the Client Secret if I close the Register API Client page?

Workday displays the plaintext Client Secret only once upon registration or regeneration. If lost, open View API Clients, locate the client on the API Clients tab, and run Generate New API Client Secret from its related actions menu.

### Should I enable Support Proof Key for Code Exchange (PKCE) on confidential web servers?

Yes. Enabling PKCE with S256 prevents authorization code interception attacks for both public desktop/mobile clients and confidential server-rendered applications.

### Can one Register API Client entry hold multiple Redirection URIs?

Yes. You can add multiple HTTPS callback URLs in the Redirection URI grid so Sandbox or multi-channel applications can complete callbacks without registering duplicate clients.

### Why does Workday return an error before showing the sign-in screen?

Pre-login failures on the Authorize Endpoint almost always mean OAuth 2.0 Clients Enabled is unchecked in Edit Tenant Setup - Security, the client\_id belongs to another tenant, or the redirect\_uri parameter does not exactly match the registered URI.

## Sources checked

-   [Workday Admin Guide — Register API Clients](https://doc.workday.com/admin-guide/en-us/authentication-and-security/authentication/oauth/dan1370797831010.html)
-   [Workday Admin Guide — Edit Tenant Setup - Security](https://doc.workday.com/admin-guide/en-us/manage-workday/tenant-configuration/tenant-setup/dan1370796470031.html)
-   [Workday Admin Guide — Live Data Query User-as-Self Authentication](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-live-data-query-/set-up-user-as-self-auth-for-ldq.html)

## Related guides

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

-   [### Register API Client vs. Register API Client for Integrations in Workday Use Register API Client with Authorization Code Grant and PKCE when external apps act on behalf of a signed-in worker. Reserve Register API Client for Integrations for headless background jobs bound to a single Integration System User.](https://kiweely.com/guides/workday-register-api-client-vs-api-client-for-integrations)
-   [### Scoping Workday API Client Functional Areas for Least-Privilege Access Workday API Client Scope (Functional Areas) acts as a hard ceiling, never a permission grant: an API request succeeds only when the Functional Area is enabled on the client AND the signed-in worker’s security groups hold permission on the underlying domain or business process.](https://kiweely.com/guides/workday-api-client-functional-areas-least-privilege-scoping)
-   [### 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.](https://kiweely.com/guides/workday-oauth-refresh-token-expiration-rotation-revocation)
-   [### Fixing Workday OAuth invalid\_client, unauthorized\_client, and Redirect URI Errors Resolve Workday OAuth 2.0 handshake errors by matching each exact HTTP error code—invalid\_client, unauthorized\_client, invalid\_grant, and redirect\_uri mismatch—against your View API Clients settings, tenant endpoint URLs, and PKCE S256 verifier.](https://kiweely.com/guides/workday-oauth-invalid-client-unauthorized-client-redirect-uri)

### More guides on More Workday guides

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

-   [Why Workday Absence Balances or Time Calculations Don’t Update After a Retro Job Change](https://kiweely.com/guides/workday-time-tracking-absence-retro-recalculation-errors)
-   [Troubleshooting Workday Compensation Cycle Eligibility, Proration, and Bonus Rounding Mismatches](https://kiweely.com/guides/workday-advanced-compensation-eligibility-bonus-rounding-errors)
-   [How to Fix Workday ACA 1095-C Code 2C Mismatches and Update Annual Affordability Thresholds](https://kiweely.com/guides/workday-aca-1095c-errors-affordability-setup)
-   [How to Reopen Workday Open Enrollment for One Employee After the Window Closes](https://kiweely.com/guides/workday-reopen-open-enrollment-single-worker)
-   [Why is a worker’s Workday Open Enrollment On Hold or missing after a backdated change?](https://kiweely.com/guides/workday-open-enrollment-stuck-disappeared-elections)
-   [How to Configure or Opt Out of the Modernized Workday Worker Profile and Private Tab](https://kiweely.com/guides/workday-worker-profile-header-private-public-tabs)
-   [How Future-Dated Dependents and ‘View Dependent As Of’ Work in Workday Benefits](https://kiweely.com/guides/workday-dependent-effective-dating-future-dependents)
-   [How Workday Data Cloud Zero-Copy Sharing Works with Snowflake, Databricks, and BigQuery](https://kiweely.com/guides/workday-data-cloud-zero-copy-snowflake-databricks)

### From the blog on More Workday guides

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

-   [Hiring a Workday FDE: Interview Checklist from Posting Quals](https://kiweely.com/blog/hiring-a-workday-fde-interview-checklist)
-   [Workday FDE Flex Work and Travel: 50% Field Rule and 20% Travel](https://kiweely.com/blog/workday-fde-flex-work-and-travel)
-   [How Workday FDEs Productize Field Insights](https://kiweely.com/blog/workday-fde-product-feedback-loop)

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