> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workday

> MCP server for Workday HCM: workers, time off, time tracking, and business process actions

<Info>
  **Beta.** This is a deploy-only connector: Runlayer hosts the MCP server, and
  it authenticates to your Workday tenant using an OAuth 2.0 API client that
  your **Workday administrator** registers.
</Info>

Connect your AI assistant to [Workday](https://www.workday.com/) for HR
workflows across workers, time off, time tracking, and business process
approvals. The connector uses the **Authorization Code Grant with PKCE**, so
each user authorizes with their own Workday identity and calls run with their
own permissions.

## Tools and required scopes

Each tool calls a specific Workday REST API service. On your API client, enable
the **Scope (Functional Area)** that secures the services for the tools you plan
to use.

<Note>
  Functional-area names can vary slightly by Workday version. The authoritative
  requirement for any operation is the **Secured by** section of that API in
  your tenant's Workday REST API reference. The table maps each tool group to
  the API service it calls (which is fixed) and the functional area that
  typically secures it.
</Note>

| Workday API service                    | Scope (Functional Area)         | Tools                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `absenceManagement` (v3)               | Time Off and Leave              | `request_time_off`, `correct_time_off_entry`, `get_time_off_details`, `get_time_off_entry`, `get_time_off_balances`, `get_eligible_absence_types`, `validate_time_off_dates`, `get_leaves_of_absence`                                                                                                                                    |
| `timeTracking` (v5)                    | Time Tracking                   | `create_time_clock_event`, `get_time_clock_events`, `create_worker_time_block`, `update_worker_time_block`, `delete_worker_time_block`, `get_worker_time_block`, `get_worker_time_totals`                                                                                                                                                |
| `common` (v1)                          | Tenant Non-Configurable         | `list_workers`, `get_worker`, `get_direct_reports`, `get_worker_organizations`, `get_managed_orgs`, `get_worker_history`, `get_time_off_plans`, `create_business_title_change`, `create_job_change`, `list_supervisory_organizations`, `get_supervisory_organization`, `get_org_workers`, `list_organizations`, `get_job_change_reasons` |
| `staffing` (v7)                        | Staffing                        | `initiate_org_assignment_change`, `get_org_assignment_change`, `update_org_assignment_business_unit`, `create_worker_skill_items`, `get_worker_skill_items`                                                                                                                                                                              |
| `person` (v4)                          | Personal Data                   | `get_personal_information`, `get_home_address`, `get_preferred_name`, `get_home_contact_change`, `add_home_phone_number`, `get_work_contact_change`, `update_work_contact_change`, `submit_work_contact_change`                                                                                                                          |
| `businessProcess` (v1)                 | Business Process Administration | `list_events`, `get_event`, `get_event_in_progress_steps`, `get_event_remaining_steps`, `get_event_comments`, `cancel_event`, `rescind_event`, `list_event_steps`, `get_event_step`, `approve_event_step`, `deny_event_step`, `send_back_event_step`, `complete_todo_step`, `list_business_process_types`                                |
| `benefitEnrollmentEventOfferings` (v1) | Benefits Administration         | `get_enrollment_event`, `list_enrollment_events`                                                                                                                                                                                                                                                                                         |

<Note>
  Some services read data secured by more than one functional area (for example
  organization data under `common`). If a tool returns a permission error after
  connecting, check that API's **Secured by** requirements and add the missing
  functional area or security-group access.
</Note>

## Setup

<Note>
  Task names and screens vary by Workday version. Your Workday administrator
  should follow the tenant's own documentation for **Register API Client for
  Integrations** and the **View API Clients** report. The steps below describe
  what Runlayer needs.
</Note>

<Steps>
  <Step title="Register an OAuth 2.0 API client in Workday">
    Have your Workday administrator confirm the tenant has **OAuth 2.0 Clients
    Enabled**, then register an API client configured for the **Authorization
    Code Grant**. The connector authenticates as a **public client** using PKCE,
    so no client secret is required.

    Under **Scope (Functional Areas)**, select the areas for the tools you plan
    to use (see the table above).
  </Step>

  <Step title="Enable refresh tokens">
    Confirm the API client is configured to **issue refresh tokens**. Without
    one, Runlayer cannot renew access silently and users must re-authenticate
    each time the access token expires. Refresh-token behavior is set on the API
    client; use your tenant's Workday documentation to confirm the correct
    settings for an interactive Authorization Code client.
  </Step>

  <Step title="Register the Runlayer callback URL">
    Add Runlayer's OAuth callback URL to the API client as an **allowed redirect
    URI** (and allowed web origin if your tenant enforces origin checks), exactly
    and with no trailing slash:

    ```
    https://<your-tenant>.runlayer.com/oauth/callback
    ```
  </Step>

  <Step title="Collect the API client values">
    From the **View API Clients** report, record: **Client ID**,
    **Authorization Endpoint**, **Token Endpoint**, and **Workday REST API
    Endpoint**.
  </Step>

  <Step title="Add the connector in Runlayer">
    In Runlayer, go to **My connectors**, find **Workday**, and click **Add
    connector**. Enter the values from the previous step (see
    [Configuration Reference](#configuration-reference)), then click **Deploy
    Server**.
  </Step>

  <Step title="Authorize">
    1. On the server page, click **Connect** under **Missing Authorization**
    2. Complete the Workday login and consent flow

    <Note>
      Each user connects with their own Workday credentials, so tools run with
      that user's permissions.
    </Note>
  </Step>
</Steps>

## Configuration Reference

**Required:**

| Variable                    | Description                                                                                                                                                                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WORKDAY_TENANT`            | Your Workday tenant name (case-sensitive), e.g. the tenant segment in your Workday URLs                                                                                                                                                                        |
| `WORKDAY_BASE_URL`          | The **host only** of your Workday REST API Endpoint (scheme + host, e.g. `https://<your-workday-host>`). Do **not** include the `/ccx/api/v1/<tenant>` path — the connector adds it. Including the full path causes tool calls to fail with "not found" errors |
| `WORKDAY_OAUTH_CLIENT_ID`   | The **Client ID** from the API client                                                                                                                                                                                                                          |
| `WORKDAY_AUTHORIZATION_URL` | The **Authorization Endpoint** from the API client                                                                                                                                                                                                             |
| `WORKDAY_TOKEN_URL`         | The **Token Endpoint** from the API client                                                                                                                                                                                                                     |

The redirect URI is set automatically to your Runlayer callback URL and does not
need to be entered.

<Note>
  The authorization, token, and REST API hosts are not always the same
  (common on implementation/sandbox tenants). Use the exact endpoint values from
  the **View API Clients** report rather than assuming they share a host.
</Note>

## Troubleshooting

<Accordion title="Tool calls fail with 404 or 'not found'">
  Check `WORKDAY_BASE_URL`. It must be the host only (scheme + host, no path), not
  the full REST API Endpoint that includes `/ccx/api/v1/<tenant>`. Including the
  path causes it to be duplicated and the request to 404.
</Accordion>

<Accordion title="Users must re-authenticate frequently / no refresh token">
  This usually means the API client is not issuing a refresh token. Ask your
  Workday administrator to confirm refresh tokens are enabled for the client (see
  Setup, Step 2). Runlayer stores and uses whatever the token endpoint returns; if
  no refresh token is issued, sessions cannot be renewed silently.
</Accordion>

<Accordion title="Authorization fails or is rejected">
  Verify the Runlayer callback URL is registered on the API client as an allowed
  redirect URI (and allowed web origin), matching exactly with no trailing slash:
  `https://<your-tenant>.runlayer.com/oauth/callback`.
</Accordion>

<Accordion title="A tool returns a permission error after connecting">
  Confirm the **Scope (Functional Areas)** on the API client cover that tool's API
  service (see the table above), and that the connecting user's Workday security
  groups grant access to the underlying data.
</Accordion>

## Updating configuration

After deployment, you can update configuration via the CLI:

```bash theme={null}
# Pull existing configuration
uvx runlayer deploy pull --deployment-id <deployment-id>

# Edit runlayer.yaml locally

# Deploy updated configuration
uvx runlayer deploy
```