Follow these steps to configure Workday for REST API access. This process involves creating a dedicated integration user, setting its permissions, registering an OAuth API client, and gathering the necessary credentials for your application. This guide is aligned with Workday’s standard security practices for building robust integrations.

What we need

[] Tenant [] Client ID [] Client Secret [] Instance URL https://.myworkday.com

Step 1: Create an Integration System User (ISU)

First, create a dedicated non-human user account to own the integration process. This ISU acts as a service account, providing a clear audit trail and ensuring the integration’s stability, independent of any human user’s account status.

1. Log in to Workday as an administrator.
2. In the search bar, search for the task: Create Integration System User.
3. Enter a User Name (e.g., python_rest_api_user) and a secure Password.
4. Check the box for Do Not Allow UI Sessions to enhance security.
5. Click OK.

Step 2: Create Security Group and Assign Permissions

Next, create a security group to grant permissions to the ISU. The API client you create later will inherit the permissions of the user associated with it. This step configures the Domain Security Policies.

1. In the search bar, search for the task: Create Security Group.
2. Select Integration System Security Group (Unconstrained) from the dropdown.
3. Give the group a descriptive Name (e.g., REST_API_Permissions_Group).
4. Click OK.
5. On the next screen, add the Integration System User you created in Step 1 to this group.
6. Next, search for the task: Maintain Domain Permissions for Security Group.
7. Select the security group you just created (REST_API_Permissions_Group).
8. In the Domain Security Policies section, grant Get access to the following domains:

9. Click OK to save the permissions.

Step 3: Activate Pending Security Policy Changes

Workday requires you to formally activate all security changes before they take effect.

1. In the search bar, search for the task: Activate Pending Security Policy Changes.
2. Enter a Comment (e.g., Permissions for REST API integration.).
3. Check the Confirm box and click OK.

Step 4: Register an API Client for Integration

This is the core step for OAuth, where you configure the OAuth Scopes.

1. In the search bar, search for the task: Register API Client.
2. Select Register API Client for Integration.
3. Client Name: Give your client a clear name (e.g., Custom Python Backend).
4. Grant Type: Select Authorization Code Grant. This is the recommended and most secure grant type for external applications, enabling the use of refresh tokens.
5. Access Token Type: Select Bearer.
6. Redirection URI: Add a placeholder URI like https://www.google.com/. It is required by the UI but will not be used by your backend service.
7. Scopes (Functional Areas): Add the following scopes by searching and selecting them:
   • Staffing
   • Organizations and Roles
   • Time Off and Leave
   • System
   • Public Data
   • Tenant Non-Configurable
8. Click OK to save.
9. CRITICAL: Workday will now display the Client ID and Client Secret. Copy these immediately and store them in a secure location. The Client Secret will not be shown again.

Step 5: Generate a Refresh Token

For a backend service to run without manual intervention, you need a long-lived refresh token.

1. Search for your newly created API Client under the View API Clients report.
2. From the client’s menu, select API Client > Manage Refresh Tokens for Integration.
3. In the Workday Account field, select the Integration System User you created in Step 1. This step formally links your API client to the ISU and all of its permissions.
4. Check the Generate New Refresh Token box.
5. Click OK.
6. CRITICAL: Workday will display the Refresh Token. Copy and store it securely with your Client ID and Secret.

Step 6: Obtain the REST API and Token Endpoints

Your application needs to know where to request tokens and where to make API calls.

1. Navigate again to the View API Clients report.
2. Select your API client.
3. From the menu, select API Client > View.
4. This page will display your Workday REST API Endpoint and the Token Endpoint. Copy both of these URLs.

✅ REST API Integration Checklist

To configure our backend, we will need all of the following credentials:

• Workday Tenant Name: (e.g., yourtenant from your Workday URL)
• Client ID: (From Step 4)
• Client Secret: (From Step 4)
• Refresh Token: (From Step 5)
• Token Endpoint URL: (From Step 6)
• REST API Base URL: (From Step 6)