---
title: "Fix Workday REST API 403: Client Scope vs. Domain Security"
description: "Step-by-step method to tell whether a Workday REST API 403 Forbidden comes from a missing API Client Functional Area, Domain Security Policy, or pending…"
url: https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope
---

# Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security

A Workday REST API 403 Forbidden means OAuth authentication succeeded, but authorization failed at one of five checkpoints: API Client Functional Area scope, stale pre-edit access grant, Report/Task Domain Security Policy, Business Process Security Policy, or unactivated pending policy changes.

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

When a Workday REST API or WQL request returns `HTTP 403 Forbidden` (`S22: Permission Denied` or `Not Authorized`), your OAuth 2.0 Bearer credential is valid, unexpired, and mapped to a real Workday user—otherwise Workday would return `401 Unauthorized` (`S19`). A `403` means the request failed Workday’s two-gate authorization check: **Effective Access = API Client Functional Area Scope ∩ Signed-In User Configurable Security**.

Guessing between editing the API Client and editing security groups wastes hours, especially when unactivated policy edits or cached OAuth grants disguise whether a fix worked. Run through the five checkpoints below in exact order to isolate the blocker in minutes.

## Fast Triage Matrix: HTTP 403 Codes and Root Causes

Inspect the JSON error payload and system code returned alongside `HTTP 403` before opening Workday setup tasks:

| Error Code / Message | What Failed | First Task or Report to Check |
| --- | --- | --- |
| `403 Not Authorized` / `S22 Permission Denied` (fails for **every** user, including admins) | API Client **Scope (Functional Areas)** omits the endpoint’s functional area, or token predates scope edit |  **View API Clients** → **Edit API Client**, then generate a fresh OAuth grant |
| `403 Not Authorized` / `S22 Permission Denied` (works in Workday UI for user A, fails via API for user B) | User B’s security group lacks **View**/**Modify** on the domain or **Initiate** on the BP policy |  **Security Analysis for Securable Item and Account** |
| `403` right after editing a Domain or BP Security Policy | Security policy edit is still sitting in a pending state |  **Activate Pending Security Policy Changes** |
| `403` when security group holds **Get** and **Put** on the domain | Granted SOAP **Integration Permissions** instead of REST **Report/Task Permissions** |  **Edit Domain Security Policy Permissions** (add **View** or **Modify**) |
| `403` on `/workers/{id}/{subresource}` | Caller lacks parent resource access on `/workers/{id}` or target org is outside constrained group | Check parent endpoint `GET /common/v1/workers/{id}` and role organization assignment |
| `403` with `S33: ID User Mismatch` or `S34: Unauthorized User for ID` | Instance WID belongs to another user’s session or an inaccessible data source | Re-query the WID under the current signed-in user’s own session rather than reusing cached IDs |

## Step 1: Separate Client Scope from User Security with the UI Parity Test

Because Workday REST APIs enforce the exact same configurable security model as the Workday web application, a 30-second UI test cuts your investigation in half:

1.  Identify the exact user whose OAuth grant returned `403`.
2.  In a non-production tenant, run **Start Proxy** as that user (or ask the user to open the equivalent screen or report in Workday).
3.  Attempt the exact same read or action in the Workday browser UI:
    -   **Succeeds in the Workday UI, fails with `403` over REST:** The worker’s security groups, domain policies, and organization constraints are already working. Jump straight to **Step 2 (API Client Scope)**.
    -   **Hidden or blocked in the Workday UI too:** The API Client is not your primary blocker—the worker lacks Domain or Business Process permission, or a policy change was never activated. Jump to **Step 3, Step 4, and Step 5**.

For deeper UI permission comparison across two workers, see [why a Workday user cannot see a field, report, or task](https://kiweely.com/guides/workday-user-cannot-see-field-task).

## Step 2: Check API Client Functional Areas (and Mint a Fresh Token)

Every Workday REST endpoint declares two security metadata attributes in the Workday REST API Explorer: **Secured By Domain** (or Business Process) and **Scope** (the Workday Functional Area).

1.  Look up the failing endpoint in the REST API Explorer—for example, `GET /absenceManagement/v1/workers/{id}/timeOffPlans` lists its required Functional Area (`Absence`) and securing domains. For WQL queries (`/wql/v1/data`), the API Client needs **Scope (Functional Areas)** covering **System** (or **Reporting and Analytics** where applicable) plus every Functional Area that owns the queried data source and fields, with **Include Workday Owned Scope** selected when calling delivered system endpoints.
2.  Run **View API Clients** in Workday, locate your client on the **API Clients** tab (for user-delegated OAuth) or **API Clients for Integrations** tab (for ISUs), and open **Related Actions** → **API Client** → **Edit API Client**.
3.  Add the missing Functional Area under **Scope (Functional Areas)** and click **OK**.
4.  **Critical:** Do **not** retry with your existing Bearer string. Workday binds Functional Area scopes to the OAuth grant when the authorization code is issued. Complete a fresh `/authorize` and `/token` flow first, then re-test the REST call:

http

```
GET /api/absenceManagement/v2/gms_dpt1/workers/3aa5550b7fe348b98d7b5741afc65534/timeOffDetails HTTP/1.1
Host: wd5-services1.workday.com
Authorization: Bearer <newly_minted_access_grant>
Accept: application/json
```

## Step 3: Grant Report/Task Permissions (View/Modify), Never Just Get/Put

If the UI parity test failed—or if you are calling REST with an Integration System User that has no UI session—verify the **Domain Security Policy** column type. Workday splits domain permissions into two separate grids:

-   **Report/Task Permissions (`View` / `Modify`):** Controls both the Workday UI **and** all **Workday REST APIs** (including WQL `GET /data` and `POST /data`). Use **View** for `GET` endpoints (and WQL `POST /data`, which is a read query) and **Modify** for mutating `POST`, `PUT`, `PATCH`, and `DELETE` endpoints.
-   **Integration Permissions (`Get` / `Put`):** Controls **Workday SOAP Web Services only**.

Adding an ISU or role-based security group exclusively to **Get** and **Put** leaves every REST call returning `403 Forbidden`. Run **View Security for Securable Item** on the REST resource or WQL data source, open **Edit Domain Security Policy Permissions**, and add the security group to **View** (or **Modify**) under **Report/Task Permissions**.

## Step 4: Verify Parent Resource Access and Business Process Policies

Two structural rules in Workday REST security catch developers even after the primary domain is granted:

### Parent-Child Sub-Resource Inheritance

Workday’s REST framework requires access to the parent URI segment before evaluating the child sub-resource. Consider submitting time off on behalf of a worker:

http

```
POST /api/absenceManagement/v1/gms_dpt1/workers/3aa5550b7fe348b98d7b5741afc65534/requestTimeOff HTTP/1.1
```

To avoid `403 Not Authorized`:

1.  The caller must have `View` permission on the parent `/workers/{id}` resource (for example, `Worker Data: Public Worker Reports` or `Self-Service: Personal Information` for self).
2.  If the caller’s security group is **Role-Based (Constrained)** (such as `Manager`), worker `3aa5550b...` must sit inside a `Supervisory Organization` that the manager actually manages as of today’s effective date.
3.  For any endpoint that initiates or acts on a workflow (`requestTimeOff`, `changeBusinessTitle`, `assignPayGroup`), you must **also** open the **Business Process Security Policy** (via **Edit Business Process Security Policy Permissions**) and add the caller’s security group to the **Initiating Action** table (or **Step Action** table for approvals). Domain security alone never authorizes initiating a business process.

## Step 5: Run Activate Pending Security Policy Changes

Edits to Domain Security Policies and Business Process Security Policies remain dormant in a staging buffer until explicitly activated, whereas security group membership changes apply immediately.

1.  Run **Domain Security Policies with Pending Changes** and **Business Process Security Policies with Pending Changes** to see if an unactivated edit is holding back your permission grant.
2.  Run the **Activate Pending Security Policy Changes** task (secured by the **Security Activation** domain in the **System** functional area), enter a clear audit comment, and confirm. For automation gotchas around this step, see [activating pending security policy changes for API permissions](https://kiweely.com/guides/workday-isu-permissions-activate-pending-security-policy-changes).

## Automating Scope and Role Boundary Checks

Manually cross-referencing REST API Explorer Functional Areas against dozens of role-based security groups in Sandbox is tedious when rolling out employee-facing tools. [Kiweely Vine](https://kiweely.com/vine) inspects live tenant domain and business process policies directly during development, while [Kiweely Bridge](https://kiweely.com/bridge) (coming next) includes an AI admin agent that configures `Register API Client` Functional Areas in Sandbox and tests live prompts as real personas (`Employee`, `Manager`, `HR Partner`) so `403` boundary behavior is proven before Production rollout.

## Verification Checklist

1.  Confirm HTTP status is `403` (authorization), not `401` (expired or malformed OAuth grant) or `404` (invalid WID or hidden path).
2.  Verify the **API Client** includes the endpoint’s exact **Functional Area** in **View API Clients**, and redeem a **new** OAuth access grant after any client edit.
3.  Confirm the caller’s security group holds **View** (reads) or **Modify** (writes) under **Report/Task Permissions**—not just SOAP **Get**/**Put**.
4.  For sub-resources and workflow endpoints, confirm parent `/workers/{id}` visibility, constrained organization membership, and **Initiating Action** permission on the **Business Process Security Policy**.
5.  Run **Activate Pending Security Policy Changes** and re-run the REST call.

## Frequently asked questions

### Why am I still getting 403 Forbidden after granting Get and Put permissions on the Domain Security Policy?

Workday REST APIs (including WQL) ignore Integration Permissions (Get and Put). Every REST endpoint requires Report/Task Permissions—specifically View for GET requests and Modify for POST, PUT, PATCH, and DELETE requests—whether the caller is a human employee or an Integration System User.

### Why did adding a Functional Area to my API Client not fix my 403 error?

Existing OAuth access grants carry the scopes that existed at the moment they were issued. After editing Scope (Functional Areas) via Edit API Client, you must mint a brand-new OAuth access grant (and re-authorize if using Authorization Code Grant) before Workday evaluates the added Functional Area.

### How do I tell whether the API Client or the signed-in worker is causing the 403?

Have the exact same worker perform the equivalent read or task in the Workday browser UI (or via Start Proxy in Sandbox). If the worker can complete it in the Workday UI, worker security is already valid and the API Client is missing the Functional Area scope; if the worker cannot see it in the UI either, worker Domain or Business Process security is missing.

### Why does calling a sub-resource like /workers/{id}/requestTimeOff return 403 when the Absence domain is configured?

Workday REST sub-resources evaluate security hierarchically. The signed-in user and the API Client must hold permissions for both the parent resource (/workers/{id}, secured under Core Staffing / Worker Data domains) and the child sub-resource (/requestTimeOff, secured by Absence domains and the Request Time Off Business Process Security Policy).

## Sources checked

-   [Concept: Workday REST API Security](https://developer.workday.com/documentation/dan1370797986071)
-   [Reference: REST API Error Messages](https://developer.workday.com/documentation/GUID-6f06b090-c7b5-47cc-b929-d2a1f1116eef)
-   [Security Policy Configuration and Activation](https://doc.workday.com/workday-education/en-us/course-manuals/security-for-administrators/security-policy-configuration-and-activation.html)
-   [Security for Administrators: Integrations](https://doc.workday.com/workday-education/en-us/course-manuals/security-for-administrators/integrations.html)

## Related guides

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

-   [### How to Find Every Domain and Web Service Permission an ISU Needs in Workday (Without Guesswork) Stop guessing Workday ISU permissions: look up every web service operation, report field, and task in View Security for Securable Item, grant Get or Put access to your Integration System Security Group, and run Activate Pending Security Policy Changes.](https://kiweely.com/guides/workday-isu-permissions-activate-pending-security-policy-changes)
-   [### Why a Workday user can’t see a field, report, or task Find the domain that secures the item, compare the two users’ security groups against it, and check for a pending security policy change before assuming the setup is wrong.](https://kiweely.com/guides/workday-user-cannot-see-field-task)
-   [### Should I use RaaS, WQL or the REST API to extract data from Workday? Use RaaS for a saved report’s output, WQL for a filtered, grouped or paged extract of up to 1 million rows, and REST for small, low-latency reads of one resource. Limits and sources are in the table.](https://kiweely.com/guides/workday-raas-wql-rest)
-   [### 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)

### More guides on Integrations and APIs

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

-   [Workday Expenses REST API: create a Quick Expense, upload a receipt and submit an Expense Report](https://kiweely.com/guides/workday-expenses-rest-api-receipt-attachments-expense-lines)
-   [Designing for Workday Tenant API Concurrency and Rate Limits During Peak Employee Traffic](https://kiweely.com/guides/workday-api-rate-limits-concurrency-workforce-self-service)
-   [Calling Workday RaaS Reports with User-Delegated OAuth Instead of an ISU](https://kiweely.com/guides/workday-raas-user-delegated-oauth-vs-isu-basic-auth)
-   [Updating Preferred Name, Pronouns, and Contact Information via the Workday Person API](https://kiweely.com/guides/workday-person-api-legal-preferred-name-contact-updates)
-   [Restricting Workday OAuth Token Use by IP with Maintain IP Ranges](https://kiweely.com/guides/workday-maintain-ip-ranges-manage-authentication-policies-api)
-   [Why Browser Single-Page Apps Hit CORS and Token Limits Against Workday APIs—and How to Fix It](https://kiweely.com/guides/workday-cors-browser-api-calls-why-backend-pass-through-needed)
-   [Parsing Workday Business Process Custom Validation Errors Returned by REST and SOAP APIs](https://kiweely.com/guides/workday-business-process-validation-errors-rest-soap-responses)
-   [How Workday Audits Business Processes Initiated via REST or SOAP Web Services](https://kiweely.com/guides/workday-business-process-audit-trail-initiated-via-web-service)

### From the blog on Integrations and APIs

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

-   [Turning a Messy Client Spreadsheet into a Clean Workday EIB Load in One Conversation](https://kiweely.com/blog/messy-spreadsheet-to-workday-eib-load-with-ai)
-   [Workday REST API vs. SOAP Web Services: Why Setup Work Still Needs the Task Screen](https://kiweely.com/blog/workday-rest-api-vs-soap-coverage-gaps)
-   [Untangling Inherited Workday Studio Integrations: A Practical Modernization Playbook](https://kiweely.com/blog/untangling-inherited-workday-studio-integrations)

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