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) |
|---|---|---|
| DimensionCredential location | Legacy WS-Security ( UsernameToken )Inside <soapenv:Header><wsse:Security> XML |
User-Delegated OAuth ( Bearer Header)HTTP Authorization request header |
| DimensionRegistration task | Legacy WS-Security ( UsernameToken )None (uses Workday account password directly) | User-Delegated OAuth ( Bearer Header)Register API Client (Authorization Code Grant, Bearer) |
| DimensionWorks for SSO-only workers | Legacy WS-Security ( UsernameToken )No (requires a native Workday password) | User-Delegated OAuth ( Bearer Header)Yes (user signs in via SAML/OIDC SSO + MFA in browser) |
| DimensionTenanted WWS URL | Legacy WS-Security ( UsernameToken )https://{host}/ccx/service/{tenant}/{Service}/{version} |
User-Delegated OAuth ( Bearer Header)https://{host}/ccx/service/{tenant}/{Service}/{version} |
| DimensionWCP API Gateway URL | Legacy WS-Security ( UsernameToken )Not supported | User-Delegated OAuth ( Bearer Header)https://api.workday.com/soap/{version}/{Service} |
| DimensionEffective data scope | Legacy WS-Security ( UsernameToken )Commonly broad ISU security group | User-Delegated OAuth ( Bearer Header)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. If you are building an unattended batch job instead, use Integration System User and API client setup.
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:
- Run Register API Client in your target tenant.
- Set Client Grant Type to Authorization Code Grant and select Support Proof Key for Code Exchange (PKCE) for public, desktop, or browser-initiated flows.
- Set Access Token Type to Bearer.
- Enter your HTTPS callback URL under Redirection URI.
- 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_Resourcesworker reads, Absence forAbsence_Management, or Financial Accounting forFinancial_Management. - Select Include Workday Owned Scope if your client also calls delivered system or metadata endpoints alongside domain services.
- 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 asSubmit_Time_OfforPut_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:
- Run View Security for Securable Item and enter the exact operation name (for example,
Get_OrganizationsorGet_Workers). - Inspect the Securable Integrations count on the securing domain policy.
- 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.
- 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>:
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 Status & Fault CodeHTTP 401 Unauthorized (empty or JSON body) |
Typical faultstring or SymptomInvalid Access Token or gateway auth rejection |
Root Cause and FixThe 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 Status & Fault CodeHTTP 500 / SOAP-ENV:Client.authenticationError |
Typical faultstring or Symptominvalid username or password or invalid OAuth credential |
Root Cause and FixEither a stale <wsse:UsernameToken> block was left in <soapenv:Header>, or OAuth 2.0 Clients Enabled is unchecked in Edit Tenant Setup - Security. |
HTTP Status & Fault CodeHTTP 500 / SOAP-ENV:Client.authenticationError |
Typical faultstring or SymptomUser not authorized for web service operation / scope error | Root Cause and FixEither 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 Status & Fault CodeHTTP 500 / SOAP-ENV:Server.error |
Typical faultstring or Symptomjava.lang.IllegalArgumentException: Customer id was not specified |
Root Cause and FixYour SOAP library injected an empty or malformed UsernameToken without @tenant instead of stripping WS-Security completely when using Authorization: Bearer. |
HTTP Status & Fault CodeHTTP 500 / SOAP-ENV:Client.validationError |
Typical faultstring or SymptomInvalid request service version or Validation error occurred |
Root Cause and FixAuthentication 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. Products that connect external interfaces to Workday under employee permissions rely on this exact Bearer mechanism: Kiweely Bridge (coming next) and Kiweely 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
- OAuth 2.0 Clients Enabled is selected on Edit Tenant Setup - Security.
- The client was created via Register API Client with
Bearertoken type and every target web service’s Functional Area selected. - Your SOAP HTTP request carries
AuthorizationwithBearer <access_token>andContent-Type: text/xml; charset=utf-8, with zero<wsse:Security>elements in<soapenv:Header>. - 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.
- Paged
Get_*calls pin bothAs_Of_Effective_DateandAs_Of_Entry_DateTimeinResponse_Filterso 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.