Skip to main content

​
About Workday

Workday is a human capital management (HCM) platform. The Serval Workday integration is a per-tenant connection to your Workday environment: it gives Serval workflows live access to Workday’s REST sub-APIs (30+ modules including Staffing, Person, Absence Management, Payroll, and Recruiting), Workday Query Language (WQL), and ten Workday Web Services (SOAP) services. It also ships two installable workflow bundles - Worker Lookup, and Time Off & Benefits - so common HR lookups work out of the box. Every connection is specific to your tenant: the REST API Base URL, Token Endpoint, and optional user-auth endpoints all belong to your Workday environment. Authentication: Service account via OAuth 2.0 refresh-token grant, tied to an Integration System User (ISU) and an API Client for Integrations registered in your Workday tenant. An optional, feature-flagged per-user (3-legged) OAuth path lets certain actions run as the end user. Data sync: On-demand only. Nothing is mirrored into Serval on a schedule - workflow actions and health checks call Workday live, and a fresh access token is obtained from your tenant’s token endpoint for every call.

​
What the Workday integration enables

Anything defined in the Workday API can be accessed through Serval.

​
Get your credentials

Setting up the connection requires a Workday administrator. You will create an Integration System User (ISU), grant it the security it needs, register an API Client for Integrations, and generate a refresh token. Workday’s official API reference is the Workday REST Services Directory.
1

Create the Integration System User

In Workday, search for Create Integration System User and create the ISU (for example, ServalIntegration). The password cannot contain the characters &, <, or >.
2

Exempt the ISU from password expiration

Search for Maintain Password Rules and add the ISU to System Users exempt from password expiration.
3

Create a security group

Search for Create Security Group, choose the type Integration System Security Group (Unconstrained) (for example, Serval Integration Group), and add the ISU under Integration System Users.
4

Grant domain security policies

Search for Maintain Permissions for Security Group (Operation: Maintain; Source Security Group: your group) and add the Domain Security Policies your use case needs. The minimum for worker reads is Worker Data: Public Worker Reports with Get Only access.
Only grant the permissions you actually need. Every Serval action runs with the ISU’s permissions.
5

Activate the security changes

Search for Activate Pending Security Policy Changes and confirm.
6

Allow the group to authenticate

Search for Manage Authentication Policies, add your security group to an authentication rule with Allowed Authentication Types User Name Password or Any, then run Activate All Pending Authentication Policy Changes.
7

Register the API client

Search for Register API Client for Integrations - not Register API Client, which is a different task used only for the optional per-user flow below. Set a Client Name (for example, Serval Workday API Client), check Non-Expiring Refresh Tokens, leave Disabled unchecked, fill in Scope (Functional Areas) (see below), and save. Copy the Client ID and Client Secret.This task has no grant-type field and no confidential-versus-public choice: an integrations client is always a confidential client using the refresh-token grant. Leave Enforce Customized Access Token Expiry unchecked and Refresh Token Timeout at 0.Scope (Functional Areas) is required. The prompt shows No matches found until you type into it - it does not list every area up front. Add the areas your use case needs:Also add Integration and System for the baseline integration domains, and check Include Workday Owned Scope if you need core Workday domains that aren’t part of any functional area.
Scope is not a substitute for permissions - it caps which functional areas the access token can reach, and the ISU still needs the domain security policies granted in the earlier steps. Both must allow a call for it to succeed.
The Client Secret may only be shown once. Copy it immediately and store it securely.
8

Generate the refresh token

Search for Manage Refresh Tokens for Integrations, select your API client, add the ISU as the Authorized User, choose an expiration, generate, and copy the Refresh Token - it is not viewable again.
Choose Never for expiration if your policy allows. Every Serval-to-Workday call depends on this refresh token; if it expires, all Workday actions stop working until you update the connection.
9

Copy the endpoints

Search for View API Clients, open your API client, and copy two values: the Workday REST API Endpoint (for example, https://impl-services1.wd12.myworkday.com/ccx/api/v1/<tenant> - this maps to Serval’s REST API Base URL field) and the Token Endpoint (for example, https://impl-services1.wd12.myworkday.com/ccx/oauth2/<tenant>/token - this maps to Serval’s Token Endpoint field).Copy both verbatim. Workday includes the tenant in the token endpoint path, and the REST endpoint may include a version segment (/ccx/api/v1/<tenant>) - Serval reads only the host and the final path segment, so either form works.
10

Copy the SOAP WSDL URL

Search for Public Web Services, locate the SOAP service you use (for example, Human Resources (Public)), choose Web Services → View WSDL, and copy the service URL for Serval’s WSDL URL field.
11

Find your tenant name

Your tenant name appears in your Workday URL (for example, https://wd2-impl.workday.com/<tenant>/d/home.html), or ask your administrator.

​
Connect in Serval

1

Open the Workday connect form

In Serval, add a new Workday connection. The form collects your tenant details, OAuth credentials, and SOAP fields.
2

Enter your Tenant Name

Tenant Name (required) - for example, mycompany. Saving without it fails with: Invalid Workday configuration: tenant name is required
3

Enter the OAuth credentials

Client ID (required), Client Secret (required), and Refresh Token (required) - from the API client and refresh token you created in Workday. All three are stored encrypted. Missing values fail with, respectively: Invalid Workday configuration: client ID is required, Invalid Workday configuration: client secret is required, and Invalid Workday configuration: refresh token is required
4

Enter the endpoints

REST API Base URL (required) - for example, https://wd2-impl-services1.workday.com/ccx/api/mycompany. It must start with https:// and contain /ccx/api/ - Serval derives every REST and SOAP endpoint from this one URL. Errors on create: Invalid Workday configuration: REST API base URL is required or Invalid Workday configuration: REST API base URL must start with https://. When editing: REST API base URL must start with https:// or Invalid REST API base URL formatToken Endpoint (required) - for example, https://wd2-impl-services1.workday.com/ccx/oauth2/token. Must start with https://. Errors on create: Invalid Workday configuration: token endpoint is required or Invalid Workday configuration: token endpoint must start with https://. When editing: Token endpoint must start with https:// or Invalid token endpoint format
5

Enter the SOAP fields

WSDL URL (required by the form) - for example, https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2. ISU Username (required by the form) - for example, ServalIntegration. ISU Password (required by the form) - stored encrypted.
These three fields are required by the form but are not validated when the connection is saved, and they are not used to make requests - SOAP endpoints and authentication are derived from the REST API Base URL and OAuth credentials (see Gotchas and troubleshooting below).
6

(Optional) Name the connection

Connection Name (optional) - for example, HR Service Account. This is how the connection appears in Serval. Leave it blank to use the tenant name and ISU Username, for example mycompany (ServalIntegration). Serval identifies a Workday connection by its tenant and ISU Username, so each Integration System User gets its own connection and a Serval workspace can connect several service accounts to the same tenant without any extra setup.
7

(Optional) Configure per-user OAuth

If the per-user OAuth feature is enabled for your workspace, three optional fields appear: User-Auth OAuth Client ID, User-Auth OAuth Client Secret, and User-Auth Authorize Endpoint (placeholder https://wd2-impl-services1.workday.com/<tenant>/authorize). Leave them blank if this connection only uses the service account. These endpoints are validated when the user OAuth flow runs (not at save): both the authorize and token endpoints must be HTTPS URLs on *.workday.com or *.myworkday.com.
8

Save the connection

Save, then run the health checks below to verify everything works.
Edit behavior differs by field type. The six secret fields (Client ID, Client Secret, Refresh Token, ISU Password, User-Auth OAuth Client ID, User-Auth OAuth Client Secret) display obfuscated (•••• plus the last 4 characters) and keep their stored value if you leave them blank or unchanged, as does Connection Name. The six non-secret fields (Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, User-Auth Authorize Endpoint) are saved exactly as submitted - clearing one of them clears the stored value. The edit form prefills current values; don’t delete them unless you mean to. The connection’s display name updates only when you submit a new, non-empty Connection Name, and its API domain only when you submit a new, non-empty REST API Base URL. The connection’s identity in Serval never changes on edit.

​
Verifying the connection

Four health checks verify the connection on demand: List Workday Workers - lists up to 10 workers through the Staffing API using the service-account credential, verifying REST connectivity and worker-read permissions.
  • Success: Successfully listed [number] workers
  • Failure: Unable to list workers. - on permission errors (401/403) it adds The API credentials may be invalid or the integration user may not have the required permissions.; on Workday server errors (500/502/503) it adds Workday returned a server error. This is likely a temporary issue - please try again later.
List Supervisory Organizations - lists up to 5 supervisory organizations through the Staffing API, verifying org-structure read access.
  • Success: Successfully listed [number] supervisory organizations
  • Failure: Unable to list supervisory organizations. - with the same conditional permission and server-error suffixes as above.
Execute WQL Query - runs a one-row WQL query (SELECT worker, fullName FROM allWorkers LIMIT 1) to verify Workday Query Language access.
  • Success: Successfully executed WQL query (returned [number] result(s))
  • Failure: Unable to execute WQL query. - with the same conditional permission and server-error suffixes as above.
SOAP API - Get Workers - calls the Staffing SOAP service’s Get_Workers operation requesting a single worker, verifying SOAP connectivity.
  • Success: Successfully connected to Workday SOAP API (retrieved [number] worker(s))
  • Failure: Unable to connect to Workday SOAP API. - with SOAP-specific suffixes: on authentication errors, The ISU username or password may be invalid. Please check your integration configuration.; on forbidden errors, The ISU does not have permission to access the Staffing SOAP service. Please check Workday security group assignments.; on WSDL errors, Could not connect to the WSDL URL. Please verify the WSDL URL is correct and accessible.; on connection errors, Could not connect to Workday. Please verify the WSDL URL and network connectivity.; otherwise the generic permission and server-error suffixes.
If the two REST checks and the SOAP check pass but Execute WQL Query fails, your tenant likely has WQL disabled - the connection itself is fine. Worker lookups that depend on WQL (finding a worker by email or employee ID) will keep failing until WQL is enabled in your tenant, or those workflows are switched to the equivalent SOAP-based lookup (the Get_Workers operation).

​
Gotchas and troubleshooting

Serval fetches a fresh access token from your Token Endpoint on every single call - there is no token caching for the service account. If Workday reports that it rejected the OAuth client ID or client secret, update the connection with the current client credentials. If Workday reports that it rejected the refresh token, generate a new refresh token and update the connection. Use non-expiring refresh tokens where your policy allows.
S22 means Workday authenticated the call and then refused it, so the credentials, token endpoint, and REST API Base URL are all fine. Two separate gates must both allow a call, and a 403 means one of them doesn’t:
  1. The API client’s Scope (Functional Areas) - the ceiling on which functional areas that client may ever touch.
  2. The account’s domain security policies - the ISU’s security group for service-account calls, or the individual’s own Workday permissions for per-user calls.
Scope never grants access; it only caps it. Work through these in order:
  • Check the right client. Service-account calls use the client from Register API Client for Integrations; per-user calls use the separate Register API Client one. Each has its own scope, and it is easy to widen one while the other is the cause.
  • Match the scope to the endpoint’s domain, not its URL. A functional area is a bundle of security domains, and the domain securing an endpoint often belongs to a different area than the REST path suggests - /supervisoryOrganizations is secured by organization data, not Staffing. The endpoint’s “Secured by” line in the Workday REST Services Directory is authoritative.
  • Activate pending security changes. Domain policy edits do not take effect until you run Activate Pending Security Policy Changes.
  • Reconnect after a per-user scope change. Scope is bound at consent time, so users who connected before the change keep the old scope until they reconnect. Service-account calls need no equivalent step - Serval fetches a fresh access token on every call, so scope changes there apply immediately.
A useful signal: if the SOAP and WQL health checks pass while the REST ones fail, look at scope first. If everything fails, look at the ISU’s domain security policies.
Some Workday tenants have WQL disabled. A failing Execute WQL Query check does not necessarily mean the connection is broken - if the REST and SOAP checks pass, the connection works. However, worker lookups that depend on WQL (such as finding a worker by email or employee ID) will not succeed until WQL is enabled, or those workflows are adapted to use the SOAP Get_Workers operation instead - the switch is not automatic.
The backend only validates Tenant Name, REST API Base URL, Token Endpoint, Client ID, Client Secret, and Refresh Token at save time. WSDL URL, ISU Username, and ISU Password are required by the form but are stored without validation and never used when requests are made - a typo in them neither blocks saving nor breaks the SOAP check. When the SOAP check fails, look at the values that actually drive SOAP calls: the REST API Base URL (every SOAP endpoint is derived from it - see the next accordion), the OAuth credentials (Client ID, Client Secret, Refresh Token), and the ISU’s security group permissions in Workday (the health check needs access to the Staffing SOAP service). Although the SOAP failure guidance mentions the ISU username and password, live SOAP requests authenticate with the same OAuth bearer token as REST requests - the ISU matters because it underpins the refresh token and the permissions model, not through the stored ISU Password field.
Every REST and SOAP endpoint Serval calls is derived from the REST API Base URL at request time - the stored WSDL URL field is not used to build request URLs. The base URL must contain /ccx/api/; if it doesn’t, SOAP endpoint derivation fails with an Unexpected API domain format error. If anything looks wrong across the board, verify this field first against the View API Clients task in Workday.
Only the secret fields and Connection Name keep their stored value when left blank during an edit. The non-secret fields - Tenant Name, REST API Base URL, Token Endpoint, WSDL URL, ISU Username, and User-Auth Authorize Endpoint - are written exactly as submitted, so submitting one of them empty blanks it out (clearing the Token Endpoint, for example, breaks every call). The connection’s display name and API domain are only updated when you submit a new, non-empty value. The edit form prefills current values; leave them in place unless you intend to change them.
Serval identifies a Workday connection by its tenant and ISU Username, so adding a second Integration System User for the same tenant creates a second connection with its own credentials and needs no extra setup. Submitting the same tenant and ISU Username again updates that connection’s credentials instead of adding a new one. Unnamed connections are labeled <tenant> (<ISU Username>); set a Connection Name on each to tell them apart more easily. If you created the app instance ahead of time (for example through Catalyst) and then connect Workday credentials to it, the credentials attach to that app instance and its existing name and external instance ID are kept.
The three User-Auth fields only appear once the per-user OAuth feature is enabled for your workspace. The user-auth app is a separate Workday OAuth API client (Authorization Code grant) stored on the service-account connection - leaving the fields blank changes nothing about the service account. Both the authorize and token endpoints are validated when the OAuth flow runs (not when you save): they must be HTTPS on *.workday.com or *.myworkday.com, since the client secret travels to these URLs. If someone tries to connect their personal Workday account before the app is configured, the attempt fails with: workday connection has no user-auth OAuth app configured (set the User-Auth OAuth Client ID/Secret). Other endpoint errors include: workday connection is missing the user-auth authorize/token endpoint, workday user-auth authorize endpoint "<url>" must use https, and workday user-auth authorize endpoint "<url>" is not an allowed workday host. An as-user workflow action fails at run time if the acting user has not connected their personal Workday account. User tokens are refreshed only near expiry and always against the exact connection that minted them.
Earlier versions of this documentation described SOAP support as “coming soon” and used different field names. SOAP is fully supported today, with ten Workday Web Services available. The current form labels are REST API Base URL (previously described as “REST API Endpoint”) and WSDL URL (previously “Web Services Endpoint URL”). The WSDL URL should now be a full versioned service URL (for example, https://wd2-impl-services1.workday.com/ccx/service/amn1/Human_Resources/v28.2), not a bare /ccx address.
Need help? Contact support@serval.com for assistance with your Workday integration.