Key takeaways

• Workday has three API surfaces over one tenant: SOAP (Workday Web Services) for batch and bulk work, REST for interactive calls, and RaaS for read-only report extracts.
• Authentication gets a call accepted. What comes back is decided by the Integration System User (ISU) behind it and that ISU's domain permissions.
• A call can authenticate cleanly and still return a 403 or come back incomplete. The fix is almost always a missing domain grant, not your code.
• SOAP uses an ISU password in a WS-Security header or an OAuth bearer token. REST uses OAuth. RaaS uses either, and the report must be shared with the ISU.
• Every Workday integration, built in-house or through a unified API, starts with the customer's admin creating an ISU and granting it domains. The difference is who owns everything after that.

Workday API architecture: SOAP vs REST vs RaaS

Getting the surface right only solves half the problem. The half that causes production incidents is this: a call that authenticates and a call that returns data are two different events. This guide covers all three surfaces, how to choose between them, how each one authenticates, and why an authenticated call can still come back empty or denied.

Three APIs, one Workday tenant

All three surfaces read the same tenant data. What differs is shape, direction and workload, so match the workload to the surface.

What each surface is

SOAP, or Workday Web Services (WWS)

WWS is Workday's original API layer and still its broadest. It is organized into services such as Human_Resources, Absence_Management and Payroll, each described by a WSDL and carrying its own operations. Absence Management, for example, covers balances, leave records, and time off requests and corrections, all scoped per worker. That's work you batch overnight across a whole workforce, not something you call one record at a time from a live screen.

WWS moves XML over SOAP, the same messaging standard SOAP toolchains have used for two decades. If you've never opened a WSDL, our guide to SOAP for REST developers covers the mechanics, and this Python walkthrough pulls workers from WWS end to end.

Authentication happens inside the envelope. The usual pattern sends the ISU's username (in the form username@tenant) and password in a WS-Security header:

POST https://{host}/ccx/service/{tenant}/Human_Resources/v{version}
Content-Type: text/xml; charset=UTF-8

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:bsvc="urn:com.workday/bsvc">
  <soapenv:Header>
    <wsse:Security soapenv:mustUnderstand="1"
        xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
      <wsse:UsernameToken>
        <wsse:Username>ISU_USERNAME@TENANT</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ISU_PASSWORD</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </soapenv:Header>
  <soapenv:Body>
    <bsvc:Get_Workers_Request bsvc:version="v{version}">
      <bsvc:Request_References>
        <bsvc:Worker_Reference>
          <bsvc:ID bsvc:type="Employee_ID">21001</bsvc:ID>
        </bsvc:Worker_Reference>
      </bsvc:Request_References>
      <bsvc:Response_Group>
        <bsvc:Include_Personal_Information>true</bsvc:Include_Personal_Information>
        <bsvc:Include_Employment_Information>true</bsvc:Include_Employment_Information>
      </bsvc:Response_Group>
    </bsvc:Get_Workers_Request>
  </soapenv:Body>
</soapenv:Envelope>

Each WWS endpoint carries a version in its URL, so you decide when to move. The catch runs the other way: new fields and operations only arrive in newer versions, and older versions are eventually retired. Treat version upgrades as a recurring chore on the roadmap, not a one-time setup.

REST

Workday's REST surface is JSON-based and organized by service and version. You register an API client in the tenant, choose its scope as a set of functional areas, and generate a refresh token for a Workday account, usually the ISU. Your integration exchanges that refresh token for short-lived access tokens:

# 1. Exchange the refresh token (issued for your ISU) for a short-lived access token.
#    Copy the exact token endpoint from "View API Clients" in your tenant.
curl -X POST "https://{host}/ccx/oauth2/{tenant}/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=refresh_token" \
  -d "refresh_token={refresh_token}"

# 2. Call a REST resource with the bearer token.
curl "https://{host}/ccx/api/v1/{tenant}/workers?limit=20" \
  -H "Authorization: Bearer {access_token}"

That makes REST the right fit for interactive work: a self-service portal looking up one worker, or a benefits form writing a single election, where the blast radius of any one call is small. It's also where most engineers start, because REST looks familiar. The familiarity is exactly what causes the failure the rest of this page is about.

RaaS, or Reports as a Service

RaaS starts from the opposite direction. Instead of calling a structured resource, you build a Workday report, the same kind an HR analyst builds, enable it as a web service, and call its URL to get the output back as JSON, XML or CSV. There is no write path. RaaS is read only.

# Copy the URL from the report: Web Service > View URLs > JSON.
# The report must be shared with the ISU making the call.
curl "https://{host}/ccx/service/customreport2/{tenant}/{report_owner}/{report_name}?format=json" \
  -u "{isu_username}:{isu_password}"

# Or send an OAuth 2.0 bearer token instead of basic auth:
#   -H "Authorization: Bearer {access_token}"

RaaS inherits the security of the report it's built from. A report an analyst can only run for their own division returns exactly that scope when called as a service. A report that isn't shared with the calling ISU comes back denied. That's the same failure you get from REST and SOAP, just triggered at the report level instead of the endpoint level.

That makes RaaS the right answer for a narrower job: a scheduled compliance extract, a nightly load into a warehouse, or a dashboard that needs Workday's own report logic. Bindbee supports this path too, through a separate Workday RaaS connector.

A valid token is not a permission

A call that authenticates cleanly can still come back denied, or come back with less than you asked for. OAuth 2.0 is a delegated-authorization framework: a token lets your client act as a particular account, within a particular scope. In Workday, that leaves three separate gates on every call:

1. The API client's scope. Scopes are functional areas. They limit which parts of Workday the client can touch at all.
2. The account behind the token. For integrations this is an ISU. Its Integration System Security Group and that group's domain permissions (Get, or Get and Put) decide what the call can see.
3. Business process security. For writes, the business process behind the action has to allow the initiating account to run it.

Get the OAuth half right and skip the ISU's domain grants, and the token still works. The call itself returns a 403, or returns records missing the fields you needed, because the account behind it can't see them.

This is why "my token works" and "my integration works" turn out to be different sentences.

Here is the domain list Bindbee has customers grant for a typical HR, payroll and benefits read. It's a good starting checklist for any Workday integration:

Choosing a surface, and what building it costs

Put the workload first. Moving thousands of records in a nightly load fits WWS. Calling one record at a time inside a live user flow fits REST. Needing a report's output on a schedule, and nothing more, fits RaaS.

Then ask the questions that decide the ongoing cost:

• Can this run on a schedule, or does it need to respond inside a live user flow?
• Do you need to write data back, or only read it?
• Who tracks WWS versions and API client scopes as Workday ships releases?
• Who handles it when a customer's admin changes a security group and your data shrinks?

One thing doesn't change with the answer. Whether you build it yourself or use a unified API, your customer's Workday admin creates the ISU and grants its domains. The build-versus-buy question is about everything after that: the SOAP and RaaS parsing, version tracking, normalization, retries and write-back, multiplied by every other HR system your customers use.

Where Bindbee fits

Bindbee is a unified API for 67+ HRIS, payroll, ATS and benefits systems, Workday among them. Bindbee doesn't remove the ISU. Your customer's Workday admin still creates one and grants it domain access, following a published setup guide that lists the exact domains above.

What Bindbee owns is everything after that:

• Tracking WWS versions and parsing SOAP and RaaS output.
• Normalizing Workday records into the same models as every other connected system.
• Retries, sync status and logs when something fails.
• Write-back, such as creating employees or pushing payroll inputs, through the same API.

Bindbee's Workday connector authenticates as the ISU your customer creates, the same identity a hand-built WWS integration would use. Every call stays inside Workday's domain and business process security. It doesn't route around it and it doesn't scrape screens.

The first sync starts as soon as the connection is authorized, and syncs repeat every 24 hours by default, adjustable per connection. Bindbee sends a webhook when a sync finishes, so your product knows when fresh Workday data is ready.

The honest limit: if Workday is the only system you'll ever connect to, and your team is comfortable owning ISU and OAuth configuration long term, building directly against WWS, REST or RaaS is a reasonable choice. This page covers what that requires. The case for a unified layer gets stronger with every additional system behind it, which is where most benefits and HR-tech platforms end up.

If that's you, see Bindbee's Workday connector or the full product overview. Integrating UKG Pro as well? Read our UKG Pro API authentication guide.

FAQ

Is Workday RaaS the same as the REST API?

No. RaaS publishes a custom Workday report as a read-only web service that returns JSON, XML or CSV. The REST API exposes structured resources you can also write to. Both sit behind the same Workday security, but RaaS returns whatever the report definition returns, and only to users the report is shared with.

Does an OAuth token grant access to Workday data?

Only within two limits: the functional areas the API client is scoped to, and the domains the account behind the refresh token (usually an ISU) is permitted to see. A valid token for an ISU missing a domain grant still gets a 403 or an incomplete result.

Which Workday API is best for bulk data loads?

SOAP, through Workday Web Services, is the usual fit for large scheduled or batch jobs such as nightly worker loads. REST suits low-latency interactive calls, and RaaS suits read-only report extracts.

What is an ISU in Workday?

An Integration System User is a service identity an integration runs as, instead of an employee's login. It belongs to an Integration System Security Group, and that group's domain permissions decide what the integration can read or change.

What domain permissions does a Workday ISU need to read worker data?

At minimum, Get access to Worker Data: Public Worker Reports. Most HR and benefits integrations also need Worker Data: Workers, Person Data domains for names and contact details, Current Staffing Information for employment status, and the compensation, payroll, benefits and time off domains for the data they sync.

Can I call Workday SOAP with OAuth instead of an ISU password?

Yes. Workday Web Services accept an OAuth 2.0 bearer token from a registered API client as well as an ISU username and password in a WS-Security header. Either way, the ISU's domain permissions still decide what comes back.