Workday API

Important

This guide covers the Workday API connector (workday-api), which reads workers from the Workday Staffing REST API.

It does not cover the older report-based Workday connector (workday-report), which uses a custom report URL and separate credentials. If your Clarity application was set up with a report URL, you are on the report connector and this guide does not apply.

Overview

The Clarity Workday connector reads your workers from Workday and uses them as an authoritative source of identity data (an HR feed).

For each worker Clarity stores the worker ID, email, full name and active status, plus these attributes: phone, worker type, primary job location, workspace, primary job code and title, additional job codes and titles, and the combined job code/title lists.

Read-only. Clarity does not create, update, deactivate or delete anything in Workday through this connector.

Authentication uses the OAuth 2.0 refresh-token grant with a non-expiring refresh token. There is no browser sign-in step and no consent screen — you generate a refresh token once in Workday and paste it into Clarity, and Clarity uses it to mint short-lived access tokens from then on.

Prerequisites

• Workday Integration/Security Administrator access — enough to register API clients and create or select an Integration System User.

• An Integration System User (ISU) with permission to read worker data via the Staffing web service. The ISU is the account Clarity’s API client acts as.

• The Staffing REST API available on your tenant.

• Your Workday tenant identifier and the API/OAuth base URL Workday gives you for token and API requests.

The ISU’s username and password are not entered into Clarity. You attach the ISU to the API client inside Workday; Clarity never sees or sends those credentials.

Step 1 — Create or identify the Integration System User

Create an ISU (or reuse an existing integration account) and make sure it can read worker data through the Staffing web service. Confirm the ISU is not subject to a password-expiry policy that would disable it, and that it is permitted to authenticate for integrations.

If the ISU cannot see a worker in Workday, Clarity will not see that worker either — ISU security determines the population Clarity imports.

Step 2 — Register the API client

Run the Workday task Register API Client for Integrations.

Configure it as follows:

Enabling Non-Expiring Refresh Tokens is required. If the client is registered without it, Workday rotates the refresh token on first use, the token you pasted into Clarity stops working, and the integration fails permanently with no way to recover other than re-registering. See Troubleshooting.

Scope must include Staffing. Workday derives the required scope from the service name in the API path — Clarity calls /ccx/api/staffing/v7/{tenant}/workers, so the Staffing functional area must be on the client’s scope list. Without it, Workday still issues a token, but one carrying no functional access, and the sync returns no usable worker data.

Access to a Workday API has two independent requirements, and both must be satisfied: the API client scope (this step) and the ISU’s security group permissions (Step 1). Granting one without the other still fails.

Step 3 — Capture the Client ID and Client Secret

On saving, Workday displays the Client ID and Client Secret.

Client Secret Shown Once

The Client Secret is shown only once. Copy it immediately and store it somewhere safe. If you lose it you must generate a new secret, which invalidates the old one.

Step 4 — Generate the refresh token for the ISU

Find the API client you just registered (the View API Client for Integrations report lists them), then from the client’s Related Actions menu choose API Client → Manage Refresh Tokens for Integrations.

On that task:

1. In the Workday Account field, select the ISU from Step 1.

2. Tick Generate New Refresh Token.

3. Click OK.

Copy the refresh token that Workday returns.

Refresh Token Displayed Only Once

The refresh token is displayed once. Like the client secret, treat it as a long-lived credential — it does not expire, and anyone holding it can read the worker data the ISU can see.

Step 5 — Find your Base URL and Tenant Identifier

• Tenant identifier — the short name for your Workday instance (the tenant segment that appears in your Workday URLs).

• Base URL — the host Workday provides for OAuth 2.0 token and API requests, for example https://wd2-impl-services1.workday.com. Enter the host only, with no path and no trailing slash.

Clarity builds the endpoints from these two values:

Token: {Base URL}/ccx/oauth2/{Tenant}/token
API: {Base URL}/ccx/api/staffing/v7/{Tenant}

Step 6 — Enter the credentials in Clarity

In Clarity, add or edit the Workday application and complete all five fields. Every field is required.

Save, then run a connection test before scheduling the sync.

Already using this connector? You must re-onboard

If your Workday application was set up with an ISU Username and ISU Password, those fields no longer exist and your sync has not been able to authenticate. To restore it:

1. Follow Steps 2–4 to register an API client with non-expiring refresh tokens and generate a refresh token. If you already have a suitable API client, you only need the refresh token.

2. Open your existing Workday application in Clarity, fill in the new Refresh Token field, and confirm the Base URL, Tenant, Client ID and Client Secret.

3. Save and run a connection test.

Your previously entered ISU username and password are removed automatically — you do not need to clear them, and they are not used. The ISU itself stays exactly as it is in Workday; it is now attached to the API client rather than supplied to Clarity.

No other Clarity configuration changes. Existing identity mappings, schedules and review history are unaffected.

Troubleshooting

“No Workday refresh token is configured” / the application needs re-authenticating No refresh token is saved on the application. Complete Step 4 and enter the token in Clarity. This is the expected error for any application that has not yet been re-onboarded.

Authentication succeeded for a while, then failed permanently The API client was registered without non-expiring refresh tokens, so Workday rotated the token and invalidated the one stored in Clarity. It cannot recover on its own. Re-register the API client with Non-Expiring Refresh Tokens enabled (Step 2), generate a fresh token (Step 4), and paste it into Clarity. Clarity logs a warning identifying this specific case.

Sync completes but returns no workers, or far fewer than expected Usually ISU security rather than a connection problem — Clarity only sees workers the ISU can see. Check the ISU’s security groups and its access to the Staffing web service. It can also mean the API client’s scope omits Staffing, in which case Workday issues a token with no functional access. Clarity detects that case and re-requests a token once; if the scope is genuinely missing, fix it in Workday (Step 2).

“Invalid client” from the token endpoint The Client ID or Client Secret is wrong, or the secret was regenerated in Workday after it was entered into Clarity. Re-copy both from the API client and re-save.

403 errors from the API even though the token is issued The ISU is authenticating but is not authorised for the worker data being requested. Grant the ISU access to the Staffing web service and to the relevant worker population.

What Clarity does NOT do

• No writes to Workday. This connector is read-only: Clarity never creates, updates, deactivates or deletes workers, jobs or any other Workday record.

• No entitlements. Clarity imports workers as identity/HR data. It does not import Workday security groups, roles or permissions as entitlements, so a Workday application will not appear in access reviews as an entitlement source.

• No ISU credential storage. Clarity stores the client ID, client secret and refresh token. It never stores or transmits the ISU’s username or password.

• No browser-based sign-in. There is no consent screen and no redirect step — if you are waiting for one, you are on the wrong connector.

• Not the report connector. Custom-report-based Workday integrations use the separate workday-report connector and are configured differently.

Need Help?