Skip to main content

Workday

Workday is an enterprise cloud platform providing unified solutions for Human Capital Management (HCM), Financial Management, and business operations. It enables organizations to manage their workforce, payroll, recruiting, performance, compensation, expenses, and organizational structure from a single integrated system.

Authentication Types​

Workday supports OAuth 2.0 authentication:

  • OAuth 2.0 - Create an API Client in your Workday tenant with appropriate functional area permissions.
    • Pros: Secure, per-user authentication, follows enterprise security standards
    • Cons: Requires admin setup, functional area configuration needed

General Settings​

Before connecting, you need to configure your tenant information:

  • Tenant Name - Your Workday tenant identifier (e.g., acme_corp, company_impl)
    • This is the subdomain used in your Workday URL: https://{tenantName}.workday.com
    • For implementation tenants, use the full tenant name including any suffixes

Setting up OAuth 2.0​

OAuth 2.0 is the authentication method for Workday API integrations. You'll need administrator privileges in your Workday tenant.

Prerequisites​

  • Workday administrator access
  • Security functional area permissions to configure API clients
  • Knowledge of which functional areas your integration needs to access

Step-by-Step Setup​

  1. Log into your Workday tenant as an administrator

  2. In the search bar, type Register API Client for Integrations and select it

  3. Click OK to create a new API Client

  4. Fill in the API Client details:

    • Client Name: Give it a descriptive name (e.g., "Webrix AI Integration")
    • Non-Expiring Refresh Tokens: Check this box (recommended for long-term integrations)
    • Client Grant Type: Select Authorization Code

  5. Under Redirect URIs:

    • Click Add
    • Copy the Redirect URL from Webrix and paste it here
    • Click OK

  6. Under Scope (Functional Areas):

    • Click Prompt next to "Functional Areas"
    • Select all functional areas your integration needs access to (see Required Functional Areas below)
    • Click OK

  7. Click OK to save the API Client

  8. After creation, you'll see the Client ID and Client Secret:

    • IMPORTANT: Copy both values immediately - the secret is only shown once
    • Store them securely

  9. In Webrix:

    • Enter your Tenant Name (e.g., company_impl)
    • Paste the Client ID
    • Paste the Client Secret
    • Click Save Changes

  10. Click Connect to authorize the integration

  11. You'll be redirected to Workday to sign in and approve access

  12. After approval, you'll be redirected back to Webrix and connected

tip

If you lose the Client Secret, you'll need to generate a new API Client. There's no way to retrieve a lost secret.

Required Functional Areas​

The Workday connector requires access to specific functional areas based on which operations you want to use. Here's a comprehensive list:

Core Functional Areas (Required for All Operations)​

  • Staffing - View and manage worker data
  • System - Basic system access
  • Integration - API integration access

Additional Functional Areas by Feature​

Workers & Employment:

  • Personal Data (View) - Access worker personal information
  • Contact Information (View) - Access worker contact details
  • Organization and Roles (View) - View organizational structure

Absence Management:

  • Absence (View) - View time off balances and history
  • Absence (Modify) - Submit time off requests

Recruiting:

  • Recruiting (View) - View job requisitions and candidates
  • Recruiting (Modify) - Create and manage recruiting processes

Performance:

  • Performance Management (View) - View performance reviews and goals

Compensation:

  • Compensation (View) - View compensation plans and history
  • Compensation (Modify) - Modify compensation (if needed)

Financial:

  • Financial Management (View) - View expenses and suppliers
  • Accounts Payable (View) - View supplier and payment information

Projects:

  • Projects (View) - View project data
Principle of Least Privilege

Only grant functional areas that your integration actually needs. Start with View permissions and add Modify permissions only when required.

Available Operations​

The Workday connector provides 31 tools across 9 categories:

Workers / Employees (5 tools)​

  • List Workers - Retrieve all workers with pagination and filtering
  • Get Worker - Get detailed worker information by ID
  • Search Workers - Search workers by name, email, or other criteria
  • Get Worker Employment Data - Get employment history and position details
  • Get Worker Compensation - Retrieve compensation details and history

Absence Management (4 tools)​

  • Get Time Off Balances - Check time off balances by plan
  • Request Time Off - Submit time off requests
  • List Time Off Plans - View all available time off plans
  • Get Absence History - Retrieve past absences and accruals

Recruiting (4 tools)​

  • List Job Requisitions - Get all job requisitions with filtering
  • Get Job Requisition - Retrieve requisition details
  • List Candidates - Browse all candidates with filtering
  • Get Candidate - Get candidate profile and application status

Performance Management (3 tools)​

  • List Performance Reviews - Get performance reviews by worker or period
  • Get Performance Review - Retrieve review details and ratings
  • Get Worker Goals - View goals and competencies for a worker

Compensation (3 tools)​

  • Get Compensation Plans - List available compensation plans
  • Get Worker Compensation Plan - Get worker's current compensation
  • Get Compensation History - View compensation change history

Organization Structure (4 tools)​

  • List Organizations - Browse organizational units
  • Get Organization - Get organization details
  • Get Organization Hierarchy - View reporting structure
  • Get Worker Supervisory Organization - Get worker's org placement

Financial Management (4 tools)​

  • List Expense Reports - Browse expense reports with filtering
  • Get Expense Report - Get expense report details and line items
  • List Suppliers - View all suppliers/vendors
  • Get Supplier - Get supplier details and payment terms

Projects (2 tools)​

  • List Projects - Browse projects with status filtering
  • Get Project - Get project details and resources

System / Administration (2 tools)​

  • Get Custom Objects - Access custom object data
  • Search Custom Objects - Search within custom objects

Common Use Cases​

Employee Information Lookup​

Search Workers by name → Get Worker details → Get Worker Employment Data → Get Worker Supervisory Organization

Time Off Management​

Get Time Off Balances → List Time Off Plans → Request Time Off

Recruiting Pipeline​

List Job Requisitions → Get Job Requisition details → List Candidates → Get Candidate profile

Performance Review Cycle​

List Performance Reviews by period → Get Performance Review details → Get Worker Goals

Expense Report Approval​

List Expense Reports filtered by 'Submitted' → Get Expense Report details → Review line items

Organizational Insights​

Get Organization Hierarchy → Get Organization details → List Workers in organization

Troubleshooting​

"Invalid tenant name" error​

Cause: The tenant name is incorrect or formatted improperly.

Solution:

  1. Verify your tenant name from your Workday URL
  2. Use only the subdomain part (e.g., company_impl from https://company_impl.workday.com)
  3. Include any suffixes like _impl or _preview for non-production tenants
  4. Do NOT include https:// or .workday.com in the tenant name field

"Insufficient permissions" or "Access Denied" error​

Cause: The API Client doesn't have the required functional area permissions.

Solution:

  1. Go to your Workday tenant
  2. Search for View API Clients for Integrations
  3. Find your API Client
  4. Click Actions → API Client → Manage API Client
  5. Under Scope (Functional Areas), add the required functional areas
  6. Reconnect in Webrix to get a new token with updated permissions

"Invalid client credentials" error​

Cause: The Client ID or Client Secret is incorrect.

Solution:

  1. Verify you copied the complete Client ID and Secret (no extra spaces)
  2. The Client Secret is only shown once during creation
  3. If you lost the secret, you'll need to create a new API Client
  4. Update the credentials in Webrix and reconnect

"Token expired" error​

Cause: The OAuth refresh token has expired.

Solution:

  1. Click Reconnect in Webrix
  2. You'll be redirected to Workday to re-authorize
  3. Consider enabling Non-Expiring Refresh Tokens when creating API Clients

"Worker not found" or "ID not found" errors​

Cause: The worker ID or resource ID doesn't exist or has incorrect format.

Solution:

  1. Workday IDs are often in specific formats (e.g., Employee_ID, WID)
  2. Use the search or list tools first to find the correct ID
  3. Verify the ID format matches what Workday expects
  4. Some operations require the Workday WID (internal ID) rather than external employee IDs

Rate limit errors​

Cause: Too many API requests in a short time period.

Solution:

Workday enforces rate limits (~10 requests per second):

  1. Reduce the frequency of requests
  2. Use pagination with smaller page sizes to distribute load
  3. Implement delays between batch operations
  4. Contact Workday support if you need higher rate limits for your tenant

"API version not supported" error​

Cause: The API version used by the connector is not available in your Workday tenant.

Solution:

  1. Ensure your Workday tenant is up to date
  2. Different API versions become available with Workday updates
  3. Contact Workday support if specific API versions are needed
  4. Some older tenants may not have the latest REST APIs available

Best Practices​

  1. Use Non-Expiring Refresh Tokens - Enable this when creating API Clients for production integrations

  2. Grant Minimal Functional Areas - Only grant View or Modify permissions for functional areas you actually need

  3. Use Pagination - Always use pagination when listing large datasets (workers, expenses, etc.)

  4. Cache Worker IDs - If you frequently access the same workers, cache their IDs to reduce search operations

  5. Test in Implementation Tenant - Always test integrations in your implementation tenant before production

  6. Monitor API Usage - Review API call logs in Workday to ensure you're within rate limits

  7. Handle Errors Gracefully - Implement proper error handling and retry logic for API calls

  8. Document Custom Objects - If using custom objects, document the object types and field structures

  9. Respect Data Sensitivity - Compensation and personal data are highly sensitive - restrict access appropriately

  10. Keep Credentials Secure - Store Client ID and Secret securely, never commit to source control

Security Considerations​

  • Functional Area Permissions - Follow principle of least privilege when granting functional areas
  • Compensation Data - Compensation tools access highly sensitive salary information
  • Personal Data - Worker personal information is protected - ensure compliance with privacy regulations
  • Destructive Operations - Time off requests and some modifications are marked as destructive
  • Audit Logs - Workday logs all API access - regular audits are recommended
  • Multi-Factor Authentication - Use MFA for all administrator accounts that can create API Clients
  • API Client Rotation - Periodically rotate API Client credentials (recommended every 90-180 days)
  • Segregation of Duties - Use different API Clients for different purposes (read-only vs. write operations)

API Rate Limits​

Workday enforces rate limits to ensure system stability:

  • General Rate Limit: ~10 API requests per second
  • Best Practice: Implement exponential backoff when rate limits are hit
  • Pagination: Use limit and offset parameters to retrieve large datasets in chunks
  • Concurrent Requests: Be cautious with parallel requests to avoid hitting limits

If you consistently need higher rate limits, contact Workday support to discuss your use case.

Workday Terminology​

  • Worker - Any person in Workday (employee, contingent worker, etc.)
  • Tenant - Your Workday instance/environment
  • Functional Area - A security domain controlling access to specific data
  • WID - Workday ID, the internal unique identifier for objects
  • Supervisory Organization - The organizational unit a worker belongs to
  • Time Off Plan - A configuration for time off accrual (vacation, sick leave, etc.)
  • Custom Object - Tenant-specific data structures extending Workday

Additional Resources​

  • Workday Community: community.workday.com - Documentation and forums
  • REST API Explorer: developer.workday.com/rest-api-explorer - Interactive API documentation
  • Workday Support: Contact through your Workday tenant for technical assistance
  • API Versions: Different modules use different API versions (v1-v7), connector uses the latest stable version for each