Skip to content
KiweelyKiweelyKiweely

SOAP vs RaaS Basic Auth vs OAuth: which Workday credentials do I use?

API Gateway SOAP and Extend calls use OAuth Bearer. Classic SOAP web services still expect username@tenant when Workday returns Customer id was not specified. RaaS RSS and Basic Auth credentials use a Workday username and password. Match the credential to the endpoint, not to habit.

  • Checked against Workday on
  • Applies to Workday Web Services, RaaS, API Gateway
  • 5 min read
  • Published
  • By Kiweely
On this page

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 is ISU_benefits and the tenant is my_tenant, use ISU_benefits@my_tenant.
  • Fault invalid username or password: the password is wrong, or the username is missing the @tenant suffix.

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.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.