Workday does not have one authentication method for every call. The credential you need depends on the surface you hit: the API Gateway SOAP path, a classic Workday Web Services SOAP endpoint, a Reports-as-a-Service URL, or an orchestration credential. Mixing those patterns is what produces invalid username or password and Customer id was not specified.
Decision tree
| You are calling | Credential shape | Where Workday documents it |
|---|---|---|
You are callingSOAP through https://api.workday.com/soap/{version}/{serviceName} |
Credential shapeOAuth 2.0 access token as Authorization: Bearer {access-token} |
Where Workday documents itCall Workday SOAP APIs Using the API Gateway |
| You are callingExtend or Integration app SOAP through the API Gateway | Credential shapeRegister an API client, then use an OAuth flow for the access token | Where Workday documents itSOAP API Authentication and Security |
| You are callingIntegration app default SOAP credential | Credential shapeAccess Token From Initiating User (the ISU on the integration system, or the launcher if none is set) | Where Workday documents itSOAP API Authentication and Security |
| You are callingClassic Workday Web Services SOAP with a username and password | Credential shapeUsername must include the tenant: ISU_benefits@my_tenant |
Where Workday documents itWorkday Web Services Error Messages |
| You are callingRaaS RSS feed | Credential shapeHTTP Basic Auth with a Workday username and password | Where Workday documents itConcept: Reports as RSS Feeds |
| You are callingOrchestration outbound call that needs Basic Auth, OAuth, API Key, or ISU | Credential shapeCredential type on the orchestration Credentials tab | Where Workday documents itCreate Orchestration Credentials |
Start from the URL and the product surface, not from “SOAP equals Basic Auth.”
SOAP through the API Gateway
For orchestrations and external apps that authorize with the API Gateway, Workday’s documented SOAP path is:
POST https://api.workday.com/soap/{version}/{serviceName}
Content-Type: text/xml
Authorization: Bearer {access-token}The body is the SOAP envelope. Workday’s sample uses Human_Resources and Get_Workers_Request. You get {version} and {serviceName} from the SOAP API Explorer. Presentation components cannot call SOAP APIs directly; a page launches an orchestration that makes the call.
Extend apps that call SOAP through the gateway register an API client on the Developer Site and choose an OAuth flow for the access token. Integration apps usually keep the default Access Token From Initiating User setting. That token is the integration system user when one is assigned, otherwise the user who launched the integration.
Classic SOAP username and password
Older Workday Web Services clients still authenticate with a username and password on the SOAP request. Workday’s fault reference is explicit about the username format:
- Fault
Customer id was not specified: append the tenant name to the account. Example from Workday: if the account isISU_benefitsand the tenant ismy_tenant, useISU_benefits@my_tenant. - Fault
invalid username or password: the password is wrong, or the username is missing the@tenantsuffix.
Do not invent a gateway Bearer token for a classic WWS client that still expects username and password, and do not send a bare ISU name to a classic endpoint that requires @tenant.
RaaS and Basic Auth
Reports-as-a-Service exposes advanced and search reports as web service URLs. The developer RaaS concept uses the namespace form https://api.workday.com/raas/{user}/{report_name} so you do not rewrite the host when the app moves tenants. Output options include CSV, JSON, RSS, Simple XML, and Workday XML.
For RSS, Workday says the feed reader must permit SSL/HTTPS or HTTP basic authentication. When the reader prompts for sign-in, you use a Workday username and password. Orchestration Builder also offers a Basic Auth credential type with username and password for outbound API requests.
RaaS still inherits Workday domain security. Integration App Security says custom reports invoked as RaaS endpoints are covered by the same configurable security model as REST, SOAP, and WQL. A 403 from a RaaS endpoint is a domain grant problem, not a wrong auth scheme.
OAuth when the subject is a system user
Client Credentials and other OAuth2 flows return an access token. For service-to-service calls through the gateway, that token is what you put on the SOAP or REST Authorization header. Studio integrations should use their own API client and Client Credentials rather than an Extend simplified-ISU API client; Workday says that explicitly under Concept: ISU Authentication.
For interactive or user-scoped work, prefer the initiating user’s access token. Workday recommends Access Token From Initiating User for integration apps unless you deliberately need a different ISU than the one that launches the integration.
Failure modes
| Symptom | Likely cause | Fix from Workday docs |
|---|---|---|
SymptomCustomer id was not specified |
Likely causeClassic SOAP username missing @tenant |
Fix from Workday docsUse account@tenant |
Symptominvalid username or password |
Likely causeWrong password, or username without tenant | Fix from Workday docsCorrect password; append tenant |
| SymptomGateway SOAP rejects the call | Likely causeMissing Bearer token or wrong Content-Type | Fix from Workday docsSend Authorization: Bearer and text/xml |
| SymptomRaaS 403 | Likely causeDomain policy, not auth scheme | Fix from Workday docsGrant View/Get for the report’s domains on the ISU or user group |
| SymptomPage cannot call SOAP | Likely causePMD cannot call SOAP directly | Fix from Workday docsLaunch an orchestration |
Frequently asked questions
Is RaaS the same as SOAP authentication?
No. RaaS is a report web service URL with formats such as JSON or CSV. SOAP is an XML envelope against a service such as Human Resources. RSS RaaS uses HTTP basic authentication with a Workday username and password. API Gateway SOAP uses an OAuth Bearer token.
Should every new SOAP client use username@tenant?
Only for classic Workday Web Services username/password clients. New Extend and gateway callers use OAuth Bearer against api.workday.com/soap/....
Which orchestration credential should I pick?
Orchestration Builder supports API Key, Basic Auth, OAuth, and ISU. Match the type to the endpoint. For Production OAuth, Workday recommends Cred Store Reference, and recommends refreshing credentials at least a week before expiry so old and new versions overlap.
Does ISU membership replace domain grants?
No. The ISU still needs Get/Put or View/Modify on the domains that secure the operation. Authentication proves who is calling. Domain security decides what they can read or write.