> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/workday.md).

# Workday

Register an API client for integrations in your Workday tenant and connect the Appmixer Workday connector.

Workday has no global app that Appmixer could register for you. Each customer registers an API client in their own Workday tenant and enters its credentials when they connect Workday in Appmixer.

The connector uses an **API Client for Integrations** with a refresh token. A Workday administrator generates the refresh token for one Workday account, usually an Integration System User (ISU). Appmixer exchanges the refresh token for an access token at `https://<host>/ccx/oauth2/<tenant>/token`, and every call runs with the security permissions of that account. There is no browser sign-in and no redirect URL.

You need a Workday administrator with access to the **Register API Client for Integrations** and **Manage Refresh Tokens for Integrations** tasks (Security Administration domain, System functional area).

***

## 1. Prepare the Workday account

Calls run as the account you pick for the refresh token in step 3. Workday recommends a dedicated Integration System User instead of a person's account.

1. Run the **Create Integration System User** task and create a user for Appmixer:

   * **User Name**: for example `ISU_Appmixer`.
   * **New Password** and **New Password Verify**: any password that meets the rules. The API does not use it.
   * **Require New Password at Next Sign In**: cleared. Selecting **Generate Random Password** turns this option on, so set the password yourself instead.
   * **Do Not Allow UI Sessions**: selected, so the account cannot sign in through the browser.

   ![Create Integration System User](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-6535a795068f19f1f68a993f0277b2c7142b8577%2Fworkday-01-create-isu.jpg?alt=media)
2. Run **Create Security Group**. Choose **Integration System Security Group (Unconstrained)** as **Type of Tenanted Security Group**, enter a **Name**, for example `Appmixer ISU Security Group`, and click **OK**. On the next screen, **Edit Integration System Security Group (Unconstrained)**, add the ISU from the previous step under **Integration System Users** and click **OK**. To change the members later, run **Edit Security Group**.

   ![Create Security Group](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-356617f92377981d91b5a14148873db2e7e9b054%2Fworkday-02-create-security-group.jpg?alt=media)

   ![Add the ISU to the group](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-f632aa4e1830d7b8db6310215304b934ed49c68c%2Fworkday-02b-add-isu-to-group.jpg?alt=media)
3. Run **Maintain Permissions for Security Group**. Keep **Operation** on **Maintain**, select your group as **Source Security Group** and click **OK**. On the **Domain Security Policy Permissions** tab, add a row for each domain that secures the data you want to read and set **View/Modify Access**:

   * **View Only** for `GET` calls, WQL included.
   * **View and Modify** for `POST`, `PUT`, `PATCH` and `DELETE` calls.

   **Get Only** and **Get and Put** on the **Integration Permissions** tab apply to web services. The REST API does not use them; only **Run Report** does, see [Run Report](#run-report). The **Secured by** line of each endpoint in the Workday REST API Explorer names its domain.

   * **List Workers**, **Find Workers**, **Get Worker** (`/workers` of the Staffing API v6) and **List Supervisory Organization Workers**: **Worker Data: Public Worker Reports**.
   * The business title of a worker (`primaryJob.businessTitle`, and the title of the manager added by **Include Manager**): **Worker Data: Current Staffing Information**.
   * **List Direct Reports**: **Reports: Manager**.
   * **List Supervisory Organizations** (`/supervisoryOrganizations` of the Staffing API v6): **View: Supervisory Organization**. With **Include Hierarchy** turned on, also **Reports: Organization**.
   * **Get Worker** with **Include Manager** turned on: the worker domain and both supervisory organization domains above.
   * **Run WQL Query**: the **Workday Query Language** domain in the **System** functional area, plus access to the data sources and fields you query. Only unconstrained security groups can be granted this domain. The `allWorkers` data source is covered by **Worker Data: Public Worker Reports**.
   * **Run Report**: a domain that secures the report's data source, as View access here and as Get access on the **Integration Permissions** tab, and the report must be shared with the group. See [Run Report](#run-report).

   To find the domains of a data source, run **View Security for Securable Item** with its name and click **View Security**. Any one of the listed domains is enough. Some of them, for example **Worker Data: Active Employees**, cannot be granted to an integration system security group, so pick one that the domain picker offers.

   ![Maintain Permissions for Security Group](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-c53e2b450406f477ed164f0b531e379839e63f07%2Fworkday-03-maintain-permissions.jpg?alt=media)
4. Run **Activate Pending Security Policy Changes**. Check that the domains from the previous step are listed under **Domain Security Policies**, fill in **Description for Change** and click **OK**. Until you do, the permissions are pending and calls are refused. The task activates every pending change in the tenant, not only yours.

   ![Activate Pending Security Policy Changes](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-3a76d8f974db8aeb292bf8dd111ab988bc0e2ac7%2Fworkday-03b-activate-pending-security-policy-changes.jpg?alt=media)

You do not need a new refresh token after you change the permissions of the security group. Workday checks them on every call. A change of the API client's scope is different, see step 2.

***

## 2. Register the API client

1. In the Workday search bar, open the **Register API Client for Integrations** task.
2. Fill in the form:
   * **Client Name**: for example `Appmixer`.
   * **Non-Expiring Refresh Tokens**: selected, so the connected account does not stop working when a token expires.
   * **Scope (Functional Areas)**: the functional areas of the endpoints the flows call. The REST API Explorer lists the scope next to the **Secured by** domain of each endpoint.
     * **Staffing** for the worker components.
     * **Organizations and Roles** for **List Supervisory Organizations**, and for **Get Worker** with **Include Manager**.
     * **System** for **Run WQL Query**.
     * **Tenant Non-Configurable** for **Run Report**.
   * **Include Workday Owned Scope**: leave cleared.
   * **Restricted to IP Ranges**: optional. Use it to allow calls only from the IP addresses of your Appmixer instance.
3. Click **OK**.
4. Copy the **Client ID** and the **Client Secret**. Workday shows the secret only once.

![Register API Client for Integrations](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-68e8e32022731ed1a86b8c80d9a602146787808c%2Fworkday-04-register-api-client.jpg?alt=media)

A call succeeds only when both agree: the client's scope includes the functional area, and the account of the refresh token has permission on the domain. Missing either returns `403`.

To change the scope later, use **API Client → Edit API Client for Integrations** on the related actions menu of the client. After a scope change, generate a new refresh token (step 3) and reconnect the account in Appmixer.

***

## 3. Generate the refresh token

1. Open the **View API Clients** report and switch to the **API Clients for Integrations** tab.
2. Note the values at the top of the report: the **Workday REST API Endpoint** (for example `https://wd2-impl-services1.workday.com/ccx/api/v1/acme`) and the **Token Endpoint**. You need the hostname and the tenant from them in step 4.

   ![View API Clients](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-08e1adb6da77a6ad6847877228fd8f45b1bc718f%2Fworkday-05-view-api-clients-endpoints.jpg?alt=media)
3. On the related actions menu of your client, choose **API Client → Manage Refresh Tokens for Integrations**.

   ![Manage Refresh Tokens for Integrations](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-3d97e8e3fe92d498609754d49710379199917437%2Fworkday-07-related-actions-manage-refresh-tokens.jpg?alt=media)
4. In the **Workday Account** field, select the ISU from step 1 and click **OK**.

   ![Select the Workday account](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-69089d93156042d0b4c2f1f801bff9b2a868c78d%2Fworkday-08-manage-refresh-tokens-pick-account.jpg?alt=media)
5. Select **Generate New Refresh Token**, click **OK** and copy the refresh token.

{% hint style="warning" %}
If the account already has a refresh token for this client, the page is titled **Delete or Regenerate Refresh Token** and also asks you to select **Confirm Delete**. Clicking **OK** deletes the existing token, and every Appmixer account that uses it stops working until you enter the new token. If you only want to look at the existing token, click **Cancel**.
{% endhint %}

![Delete or Regenerate Refresh Token](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-36e897610e7edcd2a4abdbab05e80fdfd7a89d4d%2Fworkday-09-delete-or-regenerate-refresh-token.jpg?alt=media)

***

## 4. Connect in Appmixer

When you add a Workday component to a flow, Appmixer asks you to connect an account. The form has five fields:

| Field             | Value                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workday Host**  | The hostname of your tenant, for example `wd2-impl-services1.workday.com`. Hostname only, without `https://` or a path. It must end with `workday.com` or `myworkday.com`. |
| **Tenant**        | The tenant name, the last segment of the Workday REST API Endpoint, for example `acme` or `acme_dpt1`. Letters, digits, `_` and `-` only.                                  |
| **Client ID**     | From step 2.                                                                                                                                                               |
| **Client Secret** | From step 2.                                                                                                                                                               |
| **Refresh Token** | From step 3.                                                                                                                                                               |

Take the host and the tenant from the **Token Endpoint** of step 3: in `https://wd2-impl-services1.workday.com/ccx/oauth2/acme/token` the host is `wd2-impl-services1.workday.com` and the tenant `acme`. Two mistakes are common:

* A misspelled tenant makes Workday answer `503 Service unavailable`, the same answer it gives for a tenant that does not exist. Check the tenant name before anything else.
* The address you use to sign in to Workday (for example `acme.wd2.myworkday.com`) is not the API host and answers `404`. The API host usually contains `-services1`.

Appmixer checks the values by requesting an access token from `https://<host>/ccx/oauth2/<tenant>/token` with the client ID and secret and the refresh token. The connection is named `<tenant> (<host>)`. Appmixer requests a new access token when the current one expires, every hour when Workday returns no expiry.

You need to reconnect the account only when the refresh token or the client secret changes: after someone generates a new refresh token or a new client secret for the client.

**Make API Call** accepts a path relative to your Workday host, or a full URL on that host. Any other host is rejected so that the access token is never sent elsewhere. Type `{tenant}` in the path and Appmixer replaces it with the tenant of the account, for example `/api/common/v1/{tenant}/workers`.

### Workers and organizations

The worker components read the Staffing API, so each worker comes with the current staffing information:

* name (`descriptor`) and employee ID (`workerId`);
* work email and phone (`person.email`, `person.phone`);
* business title, supervisory organization and location with its country, all under `primaryJob`;
* worker type, for example Employee or Contingent Worker.

Workday leaves out the fields the account has no permission for and reports no error. When a field such as the business title or the email is missing from every worker, grant the security group the domain that secures it (step 1).

**List Workers** returns every active worker the account can see. **Find Workers** narrows the list down:

* **Search**: text in the worker's name or employee ID.
* **Email**: the worker's email address.
* **Supervisory Organization**: workers whose primary job belongs to the organization. Pick it from the list or enter its Workday ID or reference ID (`SO13` or `Organization_Reference_ID=SO13`). Workers of subordinate organizations are not included.
* **Location**: workers whose primary job is at the location, by Workday ID or Location ID. Both are in the output of **List Workers**.
* **Include Terminated Workers**: only active workers are returned unless you turn this on.

Workday filters by search, email and status. Its REST API has no organization or location filter, so for these two Appmixer reads all workers and keeps the matching ones. In a large tenant that takes a while: 10,000 workers are 100 requests.

**Get Worker** returns one worker by Workday ID or by reference ID such as `Employee_ID=21005`. Turn on **Include Manager** to add the line manager under `manager`: name, employee ID, email and business title. The manager is the manager of the worker's primary supervisory organization. For a worker who leads that organization it is the manager of the nearest superior organization led by somebody else. A worker at the top of the hierarchy has no `manager` in the output.

**List Supervisory Organizations** returns the active supervisory organizations with name, code, reference ID and managers. Turn on **Include Hierarchy** to add the superior (parent) organization of each one under `superior`. A top level organization has none. This takes one extra request per organization.

The REST API does not return a worker's preferred language or custom fields. Read those with **Run Report** or **Run WQL Query**.

### Run Report

**Run Report** runs a custom report through Reports-as-a-Service (`https://<host>/ccx/service/customreport2/<tenant>/<owner>/<report>?format=json`). Before you use it:

* the report must be an advanced custom report with **Enable As Web Service** selected. The option appears after you set **Report Type** to **Advanced**;
* the account of the refresh token needs a domain that secures the report's data source. For **All Active Employees**, grant **Worker Data: Current Staffing Information** (see step 1). Grant it twice in **Maintain Permissions for Security Group**: as **View Only** on the **Domain Security Policy Permissions** tab, and under **Domain Security Policies permitting Get access** on the **Integration Permissions** tab. Then activate the change;
* the report must be shared with the account of the refresh token: on the **Share** tab choose **Share with specific authorized groups and users** and add the ISU's security group. The group appears in the list only after it has access to the data source;
* the scope of the API client must include **Tenant Non-Configurable** (step 2);
* **Report Owner** and **Report Name** are the two segments after the tenant in the report's web service URL: in `.../customreport2/acme/lmcneil/Workers_Report` the owner is `lmcneil` and the name `Workers_Report`;
* **Report Prompts** are optional report prompts sent as query parameters, for example `Effective_as_of_Date` = `2026-01-31-08:00`.

Workday answers `500 The task submitted is not authorized` when one of these is missing, and `Report not found` when the owner or the name is wrong.

***

## Limits

* The list components (**List Workers**, **Find Workers**, **List Direct Reports**, **List Supervisory Organizations**, **List Supervisory Organization Workers**) return the complete result. The Workday REST API serves at most 100 records per request, so a large result takes one request per 100 records.
* **Run WQL Query** returns the complete result as well. Workday serves at most 10,000 rows per request.
* Workday publishes no per-second limit for the REST API and answers `429` when a tenant is throttled. Appmixer starts at most 10 Workday component runs per second per user and queues the rest. One run can send more than one request: a list reads its pages one after another, and **Include Hierarchy** sends up to five requests at a time. A request answered with `429` is retried up to three times.

***

## Backoffice configuration

Configuration ID: `appmixer:workday`. For how to set connector configuration values, see [Connector Configuration](https://docs.appmixer.com/getting-started/services).

You do not need any Backoffice configuration to authenticate, because every user enters the credentials of their own Workday API client. There are two optional keys:

* `listCacheTTL`: optional. How long, in milliseconds, the list of supervisory organizations offered in the **Supervisory Organization** field is cached per account. The default is `120000` (two minutes). Flow runs are not cached.
* `outputFilePrefix`: optional. A prefix for the names of CSV files created when **List Workers**, **Find Workers**, **List Direct Reports**, **List Supervisory Organizations** or **List Supervisory Organization Workers** runs with the **Store to CSV file** output type. Files are named `<prefix>-<component label in the flow>.csv`. The default is `workday-objects-export`.

```bash
appmixer service-config set appmixer:workday -u -d '{
  "listCacheTTL": 120000,
  "outputFilePrefix": "workday-objects-export"
}'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appmixer.com/connector-configuration/workday.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
