---
title: "Workday SOAP Web Services with OAuth Bearer Auth — Kiweely"
description: "Call Workday Public Web Services (SOAP XML) with an HTTP Authorization Bearer header from a user-delegated OAuth 2.0 grant instead of WS-Security UsernameToken."
url: https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth
---

# Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token

Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.

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

You can call Workday Public Web Services (SOAP) on behalf of a signed-in employee by passing an OAuth 2.0 `Authorization` header with the `Bearer` scheme on the HTTP `POST` request and leaving `<soapenv:Header/>` free of `wsse:Security` credentials. Workday authenticates the OAuth grant at the transport layer and executes the XML operation under the signed-in worker’s own security groups, constrained organizations, and domain permissions.

Most Workday SOAP examples assume an unattended Integration System User (ISU) sending a `wsse:UsernameToken` block with a static Workday password. That pattern breaks immediately when an interactive application, desktop tool, or external assistant needs to read or update SOAP-only objects as a federated SSO employee who has no Workday password. Moving authentication from the XML envelope to an user-delegated OAuth 2.0 Bearer header solves both problems: SSO and multifactor authentication stay on Workday’s sign-in screen, and every `Get_*` or `Put_*` call inherits the caller’s exact organizational boundaries.

## WS-Security UsernameToken vs. HTTP OAuth Bearer

Before changing your SOAP client, verify how transport-level OAuth differs from legacy XML header authentication across Workday’s two endpoint styles:

| Dimension | Legacy WS-Security (`UsernameToken`) | User-Delegated OAuth (`Bearer` Header) |
| --- | --- | --- |
| Credential location | Inside `<soapenv:Header><wsse:Security>` XML | HTTP `Authorization` request header |
| Registration task | None (uses Workday account password directly) |  **Register API Client** (`Authorization Code Grant`, `Bearer`) |
| Works for SSO-only workers | No (requires a native Workday password) | Yes (user signs in via SAML/OIDC SSO + MFA in browser) |
| Tenanted WWS URL | `https://{host}/ccx/service/{tenant}/{Service}/{version}` | `https://{host}/ccx/service/{tenant}/{Service}/{version}` |
| WCP API Gateway URL | Not supported | `https://api.workday.com/soap/{version}/{Service}` |
| Effective data scope | Commonly broad ISU security group | Signed-in worker’s own security groups + API Client Functional Areas |

For interactive sign-in setup when corporate SSO blocks native passwords, see [authenticating external tools with an OAuth API Client and PKCE](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password). If you are building an unattended batch job instead, use [Integration System User and API client setup](https://kiweely.com/guides/workday-integration-system-user-api-client).

## Configuring Register API Client for SOAP Operations

User-delegated SOAP access starts in the **Register API Client** task (never **Register API Client for Integrations**, which binds to a single ISU). You need the **Security Administration** domain in the **System** functional area to create the client:

1.  Run **Register API Client** in your target tenant.
2.  Set **Client Grant Type** to **Authorization Code Grant** and select **Support Proof Key for Code Exchange (PKCE)** for public, desktop, or browser-initiated flows.
3.  Set **Access Token Type** to **Bearer**.
4.  Enter your HTTPS callback URL under **Redirection URI**.
5.  Under **Scope (Functional Areas)**, add the exact Functional Area that owns every SOAP web service you plan to call—for example, **Core Staffing** and **Personal Data** for `Human_Resources` worker reads, **Absence** for `Absence_Management`, or **Financial Accounting** for `Financial_Management`.
6.  Select **Include Workday Owned Scope** if your client also calls delivered system or metadata endpoints alongside domain services.
7.  Click **OK** and record the **Client ID**, **Authorization Endpoint**, and **Token Endpoint** from the confirmation screen.

Workday enforces an intersection rule at runtime: if the SOAP operation requires a Functional Area omitted from the API Client’s **Scope (Functional Areas)** list, Workday rejects the request even if the signed-in worker is a tenant administrator.

## Domain Security: Why View Permission Still Fails on SOAP

The most frequent surprise when switching from REST or WQL to user-delegated SOAP is how Workday evaluates **Domain Security Policies**:

-   **REST and WQL endpoints** check **Report/Task Permissions** (**View** for `GET`, **Modify** for writes).
-   **SOAP web service operations** check **Integration Permissions** (**Get** for read operations such as `Get_Workers`, **Put** for write operations such as `Submit_Time_Off` or `Put_Applicant`), regardless of whether the caller is an ISU or a human employee.

Some delivered securable items carry a combined **View Get** indicator on the domain policy, meaning **Get** grants reporting access, not the reverse: holding **View** under Report/Task Permissions does **not** automatically grant **Get** on a SOAP web service operation.

To check what a specific SOAP operation requires:

1.  Run **View Security for Securable Item** and enter the exact operation name (for example, `Get_Organizations` or `Get_Workers`).
2.  Inspect the **Securable Integrations** count on the securing domain policy.
3.  Confirm that the role-based or user-based security group assigned to your human users has **Get** (for reads) or **Put** (for writes) under **Integration Permissions** on that domain.
4.  Run **Activate Pending Security Policy Changes** so the updated policy takes effect.

## Constructing the HTTP Request and Clean SOAP Envelope

Once your client exchanges the authorization code at the Workday token endpoint, construct a standard HTTP `POST` request with `Content-Type: text/xml; charset=utf-8` and your Bearer credential in the `Authorization` header.

Do **not** include `<wsse:Security>` inside `<soapenv:Header>`. Leave `<soapenv:Header/>` empty, or include only `<bsvc:Workday_Common_Header>` when you need `<bsvc:Include_Reference_Descriptors_In_Response>`:

xml

```
POST /ccx/service/gms_dpt1/Human_Resources/v43.2 HTTP/1.1
Host: services1.wd5.workday.com
Authorization: Bearer 7c3obrknwd6nnkxv0r64jdpbx
Content-Type: text/xml; charset=utf-8
wd-external-request-id: 9b2c4e10-71a4-4f2a-8c3d-110293847561
wd-external-application-id: WorkforceDirectorySync

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv:Header>
    <bsvc:Workday_Common_Header>
      <bsvc:Include_Reference_Descriptors_In_Response>true</bsvc:Include_Reference_Descriptors_In_Response>
    </bsvc:Workday_Common_Header>
  </soapenv:Header>
  <soapenv:Body>
    <bsvc:Get_Workers_Request bsvc:version="v43.2">
      <bsvc:Response_Filter>
        <bsvc:As_Of_Effective_Date>2026-11-15</bsvc:As_Of_Effective_Date>
        <bsvc:As_Of_Entry_DateTime>2026-11-15T18:00:00Z</bsvc:As_Of_Entry_DateTime>
        <bsvc:Page>1</bsvc:Page>
        <bsvc:Count>50</bsvc:Count>
      </bsvc:Response_Filter>
      <bsvc:Response_Group>
        <bsvc:Include_Reference>true</bsvc:Include_Reference>
        <bsvc:Include_Personal_Information>false</bsvc:Include_Personal_Information>
        <bsvc:Include_Employment_Information>true</bsvc:Include_Employment_Information>
      </bsvc:Response_Group>
    </bsvc:Get_Workers_Request>
  </soapenv:Body>
</soapenv:Envelope>
```

Keep `<bsvc:Response_Group>` explicit and minimal on user-delegated SOAP calls. If you omit `<bsvc:Response_Group>` on `Get_Workers`, Workday attempts to populate default worker sections—which can either slow down responses or omit sections the signed-in employee lacks domain permission to read.

If you route through the Workday Cloud Platform API Gateway (`https://api.workday.com/soap/v43.2/Human_Resources`) instead of the tenanted `/ccx/service/...` path, do not embed the tenant name in the URL path; the gateway resolves the target tenant directly from the OAuth Bearer grant.

## Diagnosing Common SOAP Faults and Gateway Status Codes

Because SOAP 1.1 wraps application and security errors inside XML fault envelopes, your HTTP client will frequently receive `HTTP 500 Internal Server Error` when authentication, scope, or domain permissions fail on `/ccx/service/` URLs. Parse `<faultcode>` and `<faultstring>` before retrying:

| HTTP Status & Fault Code | Typical `faultstring` or Symptom | Root Cause and Fix |
| --- | --- | --- |
| `HTTP 401 Unauthorized` (empty or JSON body) | `Invalid Access Token` or gateway auth rejection | The Bearer value expired, was revoked when the Workday session timed out, or hit the wrong regional gateway (`api.workday.com` vs `api.eu.wcp.workday.com`). Refresh or re-authorize. |
| `HTTP 500` / `SOAP-ENV:Client.authenticationError` | `invalid username or password` or invalid OAuth credential | Either a stale `<wsse:UsernameToken>` block was left in `<soapenv:Header>`, or **OAuth 2.0 Clients Enabled** is unchecked in **Edit Tenant Setup - Security**. |
| `HTTP 500` / `SOAP-ENV:Client.authenticationError` | User not authorized for web service operation / scope error | Either the API Client lacks the service’s Functional Area in **Register API Client**, or the worker’s security group lacks **Get**/**Put** **Integration Permissions** on the domain (or policy changes were never activated). |
| `HTTP 500` / `SOAP-ENV:Server.error` | `java.lang.IllegalArgumentException: Customer id was not specified` | Your SOAP library injected an empty or malformed `UsernameToken` without `@tenant` instead of stripping WS-Security completely when using `Authorization: Bearer`. |
| `HTTP 500` / `SOAP-ENV:Client.validationError` | `Invalid request service version` or `Validation error occurred` | Authentication succeeded, but the `bsvc:version` attribute omitted the leading `v` (for example `43.2` instead of `v43.2`) or referenced a WID outside the worker’s constrained organization visibility. |

When testing write operations (`Put_*`, `Submit_*`, `Import_*`), include the HTTP header `X-Validate-Only: 1` (supported on WWS v27.0 and later) to verify both OAuth authorization and schema validation without persisting any change to the tenant.

## Where User-Delegated SOAP Fits Alongside REST and WQL

Even on modern tenants, dozens of administrative, benefits, financial, and staffing reads only exist in Workday Public Web Services—for details on choosing the right surface, see [when to use RaaS, WQL, or REST](https://kiweely.com/guides/workday-raas-wql-rest). Products that connect external interfaces to Workday under employee permissions rely on this exact Bearer mechanism: [Kiweely Bridge](https://kiweely.com/bridge) (coming next) and [Kiweely Leaf](https://kiweely.com/leaf) (coming next) execute SOAP reads alongside REST, WQL, and RaaS using each signed-in worker’s user-delegated OAuth grant so legacy service coverage never requires a shared ISU credential.

## Verification Checklist

1.  **OAuth 2.0 Clients Enabled** is selected on **Edit Tenant Setup - Security**.
2.  The client was created via **Register API Client** with `Bearer` token type and every target web service’s Functional Area selected.
3.  Your SOAP HTTP request carries `Authorization` with `Bearer <access_token>` and `Content-Type: text/xml; charset=utf-8`, with zero `<wsse:Security>` elements in `<soapenv:Header>`.
4.  The signed-in user’s security group holds **Get** (or **Put**) under **Integration Permissions** on the securing domain, and **Activate Pending Security Policy Changes** has completed.
5.  Paged `Get_*` calls pin both `As_Of_Effective_Date` and `As_Of_Entry_DateTime` in `Response_Filter` so page 2 and beyond return a consistent snapshot.

## Frequently asked questions

### Should I include a WS-Security UsernameToken block when sending an OAuth Bearer header?

No. Leave the SOAP Header element empty (or include only non-credential headers such as Workday\_Common\_Header). Sending both an HTTP Authorization Bearer header and a WS-Security UsernameToken causes conflicting credential evaluation and SOAP authentication faults.

### Which Domain Security Policy permissions do SOAP calls require under user-delegated OAuth?

Workday SOAP operations check Integration Permissions (Get for read operations and Put for write operations) on the securing domain, even when the caller is a human worker rather than an Integration System User. Report/Task Permissions (View and Modify) alone do not authorize SOAP web service operations unless the domain item explicitly carries View Get.

### Why does Workday return HTTP 500 instead of HTTP 401 or 403 when a SOAP Bearer call fails?

On tenanted Public Web Services endpoints, Workday follows the SOAP 1.1 specification and wraps authentication, scope, and validation failures inside a SOAP-ENV:Fault XML envelope returned with HTTP status 500 Internal Server Error. Only gateway-level routing rejections before the SOAP processor return HTTP 401 or 403.

### Can an SSO-only employee without a Workday password invoke SOAP web services?

Yes. Register an API Client using Register API Client with Authorization Code Grant and PKCE enabled. The employee completes corporate SSO and MFA in the browser, and the resulting OAuth access string authenticates SOAP calls over HTTPS.

## Sources checked

-   [Call Workday SOAP APIs Using the API Gateway](https://developer.workday.com/documentation/ouv1543606422515)
-   [SOAP API Authentication and Security](https://developer.workday.com/documentation/GUID-4c354bdb-06cd-461d-a632-ea8303beaedb)
-   [Reference: Workday Web Services Error Messages](https://developer.workday.com/documentation/hug1399941147933)
-   [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 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)
-   [### 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)

-   [Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope)
-   [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)

### From the blog on Integrations and APIs

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

-   [Before-and-After Diffs and One-Step Rollback for Integration Fixes](https://kiweely.com/blog/before-and-after-diffs-and-one-step-rollback)
-   [What Is an AI-Built Workday Integration Platform Outside the Tenant?](https://kiweely.com/blog/what-is-ai-built-workday-integration-platform)
-   [Nothing Kept After a Run: Zero-Retention Workday Integrations](https://kiweely.com/blog/nothing-kept-after-a-run-zero-retention-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.
