How to provision Workday API access through an ISU and security group

Key takeaways

• Workday API access is five things that have to line up: an Integration System User (ISU), an Integration System Security Group (ISSG), domain permissions, business process permissions for some writes, and activation.
• Use one ISU per integration, block UI sessions, and exempt it from password expiry.
• Integration Permissions (Get, Put) control web service calls. Report/Task Permissions (View, Modify) control reports and tasks.
• A write that triggers a business process needs business process security on top of the domain grant.
• Nothing is live until you run Activate Pending Security Policy Changes.

Workday API access isn't a password you request. It's a chain of security objects that all have to agree before a single call succeeds: a non-person account, the group it belongs to, the domains that group can touch, the business processes those domains don't cover, and the activation step that makes any of it real.

Share one account across integrations and a compromised integration can reach whatever the others touch. Skip the business process layer and a write fails with no obvious cause. Skip activation and a change that looks saved still isn't live.

This guide walks through each step in order, with the two decisions that most often go wrong, constrained versus unconstrained scope and the business process trap, and a quick way to test the result. For how each Workday API surface authenticates once this is in place, see our Workday API authentication guide.

What Workday API access requires

A username and password authenticate a person. Workday integrations run as an Integration System User, a non-person account that represents exactly one integration. The ISU carries no access by itself. It has to belong to an Integration System Security Group, and the group is what gets granted access.

If the integration comes from a vendor, the vendor should give you the list of domains it needs. Either way, the steps below are done by a Workday security administrator in your tenant.

Step 1: create the Integration System User

1. Run Create Integration System User with a name that identifies the integration, for example ISU_Benefits_Sync. One ISU per integration, never a shared account.
2. Tick "Do Not Allow UI Sessions." The ISU never needs to log in to Workday's interface, and blocking it removes an attack surface.
3. Exempt it from password expiry. Add the ISU to the exempt list in Maintain Password Rules. Otherwise the integration stops working the day the password expires.

This is least privilege applied to Workday. NIST's SP 800-53 control AC-6 states the principle: allow only the access needed to accomplish assigned tasks. A dedicated ISU per integration is what makes that enforceable.

Step 2: create the security group and choose its scope

Create an Integration System Security Group with Create Security Group, then add the ISU to it. Until the group is granted domains, the ISU can authenticate and still see nothing.

The choice that decides how far access reaches is the group type:

• Unconstrained applies to every instance of the data its domains cover, with no organizational limit.
• Constrained limits the same access to part of the organization, such as one company or supervisory organization.

Choose constrained when the integration genuinely only needs one slice of the organization. Choose unconstrained when it needs the whole population, which is the case for most payroll and benefits integrations. Forcing a constrained group onto a whole-company integration just creates a list of organization exceptions to maintain.

Step 3: grant domains, and watch for the business process trap

A new group has no access until it's added to security policies. Workday has two kinds:

• Domain security policies control access to a category of data, such as worker data or compensation.
• Business process security policies control who can initiate or approve steps in a process, such as Hire or Change Job.

Use Maintain Domain Permissions for Security Group to add domains. Here's the list Bindbee has customers grant for a typical HR, payroll and benefits read, a useful starting point for any integration:

Domain access covers most integrations on its own. It stops being enough when a write triggers a business process. Workday's own training notes that domain policies secure most web service operations, but some Put operations are secured by business process policies because they launch a process. A read-only sync never meets this layer. A write that hires someone or changes a job does, and a missing business process grant is one of the most common reasons a domain setup that looks right still fails.

Step 4: match the permission type to the operation

Each domain security policy has two permission grids, and they control different things:

Most outbound integrations only need Get. Add Put only on the domains the integration actually writes to, rather than granting it everywhere out of caution.

Step 5: activate, authenticate and test

1. Activate the changes. Run Activate Pending Security Policy Changes and add a comment. Nothing above takes effect until you do.
2. Set up authentication. For SOAP web services, the ISU's username (in the form username@tenant) and password go in a WS-Security header. For REST, register an API client for integrations and generate a refresh token for the ISU, which your integration exchanges for access tokens.
3. Test with one worker. A single-record Get_Workers call tells you quickly which layer is wrong.

curl -s -X POST "https://{host}/ccx/service/{tenant}/Human_Resources/v{version}" \
  -H "Content-Type: text/xml; charset=utf-8" \
  --data-binary @- <<'XML'

  
    
      
        ISU_USERNAME@TENANT
        ISU_PASSWORD
      
    
  
  
    
      1
      true
    
  

XML

# SOAP fault      -> credentials or ISU password rules
# Worker, no name -> missing Person Data domains
# No worker       -> missing Worker Data: Public Worker Reports

For a full Python client built on this, see Workday Get_Workers requests in Python.

When access fails: diagnosing common errors

Provisioning this once, or once per system

Everything above is for one integration in one Workday tenant. Add ADP, UKG Pro and a benefits platform and you repeat the idea against each system's own security model, which rarely looks anything like Workday's.

A unified API absorbs most of that repetition, but not all of it. With Bindbee, your customer's Workday admin still creates the ISU and grants its domains, following a published setup guide with the exact domains listed above. Bindbee's Workday connector then authenticates as that ISU, so every call stays inside Workday's security, and everything after it is Bindbee's job:

• One API for Workday and 67+ other HRIS, payroll, ATS and benefits systems, with 40+ unified data models.
• Version tracking, SOAP and RaaS parsing, and normalization into the same models for every system.
• Read and write through the same API, with syncs every 24 hours by default, adjustable per connection.

See Bindbee's Workday connector or the product overview. We build the integrations. You build the product.

FAQ

What is the difference between a constrained and an unconstrained ISSG?

An unconstrained Integration System Security Group reaches every instance of the data its domains cover. A constrained group limits that access to part of the organization, such as one company or supervisory organization. Most multi-company HR and benefits integrations use unconstrained groups.

Is domain access enough for a Workday integration to write data?

Not always. Domain security covers most web service operations, but a Put operation that triggers a business process, such as a hire or job change, also needs the group added to that business process security policy.

Why does a new Workday ISU have no access?

An ISU carries no access on its own. It has to belong to an Integration System Security Group, that group needs domain security policies granted, and the changes only take effect after running Activate Pending Security Policy Changes.

What is the difference between Get/Put and View/Modify in Workday?

Get and Put are Integration Permissions and control web service operations. View and Modify are Report/Task Permissions and control reports, tasks and reporting data sources. Both are set on the same domain security policy.

How does a Workday ISU authenticate to the API?

For SOAP web services, with the ISU's username and password in a WS-Security header, or with an OAuth 2.0 bearer token. For REST, through an API client registered for integrations, with a refresh token generated for the ISU.