Developers ·

Workday API Authentication Guide: ISU, OAuth 2.0, and Tokens

Akshat Jain
6 min read
Table of Contents

Workday API authentication requires configuring an Integration System User (ISU) and registering an OAuth 2.0 API client. Engineers then pass bearer tokens to access endpoints. This guide covers how to set up a Workday ISU, how Workday API OAuth 2.0 authentication works, and how to manage token refresh.

Key takeaways:

  • Workday API authentication can use OAuth 2.0 bearer tokens for both SOAP and REST endpoints.
  • Integration System Users (ISUs) isolate third-party integration access from standard employee accounts.
  • Access tokens expire in 4 hours, and refresh tokens expire in 24 hours.

For a broader overview of available endpoints, read the Workday API Integration Guide: Setup & Examples.

Configuring a Workday Integration System User (ISU)

A Workday Integration System User (ISU) is a dedicated account for third-party applications. It keeps your B2B SaaS authentication separate from standard employee accounts, so system requests don’t depend on human user lifecycles.

To set up an ISU, follow these steps:

  1. In your Workday tenant, run the Create Integration System User task and enter a username and password for the integration.
  2. Give the ISU the permissions it needs. The Workday credentials guide notes that the ISU needs domain security policies assigned to it.
  3. If you will call REST endpoints, run the Register API Client for Integrations task. Workday REST APIs support OAuth authentication types only, so REST access needs an API client in addition to the ISU.

Once the ISU exists, capture the credentials for the integration. The required setup parameters are the URL, the Integration System User name, the Integration System User password, and the Tenant Name.

Registering an OAuth 2.0 API Client for Workday

Workday allows authenticating both SOAP and REST API requests using OAuth 2.0 Bearer tokens. In this model, OAuth 2.0 authenticates all API access, for Workday REST API authentication and Workday SOAP API authentication alike.

Workday’s developer documentation states that to authenticate Workday and external REST API calls from external apps or integrations, register your API client on the Developer Site and choose an OAuth authentication flow to generate the access token.

During setup, you define the integration permissions. Workday’s admin guide says to select the functional scopes you would like exposed in the catalog to users when they authenticate.

Record the REST Client ID and REST Client Secret from this configuration. This Workday credentials guide explains that a token is requested from the /token endpoint using the REST API client’s credentials, and the token is then sent as a Bearer token. For context on how this pattern compares to others, read about the 5 Best API Authentication Methods to Boost Security.

Managing Workday API Token Lifetimes and Refresh Logic

A Workday API token expires after a fixed window, so build logic to request new tokens before the old ones expire.

Workday OAuth 2.0 token request and refresh loopWorkday APIWorkday token endpointB2B SaaS AppWorkday APIWorkday token endpointB2B SaaS AppAccess token valid for 4 hoursBefore the 4-hour window endsRequest token with REST API client credentialsAccess token and refresh tokenRequest data with Bearer access tokenReturn dataRequest new access token with refresh tokenNew access token

Workday’s AI admin guide notes that the access token expiry time is 14400 sec (4 hours). The refresh token expiry time is 24 hours.

Store the REST Refresh Token securely in your database. Your application must use it to request a new access token before the 4-hour window expires.

Making Authenticated Requests to the Workday REST API

With a valid access token, you can query endpoints. Workday’s documentation states that a Workday REST API endpoint uses this URL format: https://api.workday.com/{service}/{version}/{resource}.

To access these resources, Workday’s authentication guide instructs developers to set the Authorization header in the requests you send to the Workday REST API endpoint. Set the Authorization header to the token_type value and access_token value.

When querying collections, use pagination parameters. Workday’s pagination concept guide states that pagination is available with GET collection endpoints that provide the limit and offset query parameters. The same guide defines limit as the maximum number of items to include in a single response, noting the default value is 20, and the maximum is 100.

To see authenticated, paginated requests applied in code, see how to Get Employee Leave Data from Workday API using Python.

Troubleshooting Common Workday API Authentication Errors

Authentication failures usually trace back to one of three areas: the ISU setup, the OAuth 2.0 client setup, or token lifetimes. Work through them in this order:

  • ISU permissions: confirm the ISU has the domain security policies it needs. Without them, valid credentials still cannot reach the data.
  • OAuth 2.0 client scopes: if the token is valid but access is denied, verify you selected the correct functional scopes exposed in the catalog during setup.
  • Token lifetimes: check that your app requests a new access token before the 4-hour limit, and that the refresh token is used within its 24-hour lifetime.
  • Setup parameters: check that the URL, Integration System User name, password, and Tenant Name match the values captured during setup.

Logging when each token was issued makes it easier to tell an expired token apart from a permissions problem.

How to do this with Knit

With Knit: Knit’s pre-built embedded auth UI handles OAuth, API keys, and token management per provider. Your team writes no auth code; Knit manages the whole authentication lifecycle. It handles redirect URIs, secure token exchange, and automatic background refreshes.

Manual Workday integration compared with routing through KnitWith KnitYour appKnit unified APIWorkday APIManual Workday integrationYour appISU credentialsToken refresh loopError handlingWorkday API

To configure Workday (app ID workday), you register your client credentials using the Register OAuth Credentials API endpoint (POST /oauth.creds.register).

The Knit API returns a success flag and a data object confirming the registration. For more examples of authenticating HRIS systems, visit the Developers category.

Frequently Asked Questions

How do I configure an Integration System User (ISU) in Workday?
Run the Create Integration System User task in your Workday tenant, set a username and password, and assign the ISU the domain security policies it needs. Then capture the URL, Integration System User name, password, and Tenant Name to authenticate your third-party application.

How do I generate an OAuth 2.0 bearer token for the Workday API?
Register your API client on the Developer Site and choose an OAuth authentication flow. Request a token from the /token endpoint using the REST API client’s credentials, then send it as a Bearer token in the Authorization header.

How long do Workday API tokens last and how do I refresh them?
The access token expiry time is 14400 sec (4 hours). The refresh token expiry time is 24 hours. You must use the refresh token to request a new access token before the 4-hour window ends.

Why am I getting authentication errors when querying the Workday API?
Errors usually come from expired access tokens, missing ISU domain security policies, or the wrong functional scopes. Check the token’s age against the 4-hour limit, confirm the ISU’s permissions, and confirm the scopes selected during setup.

Written by Akshat Jain

Coding chaos into innovation and building from zero to scale

Keep Reading

#1 in Ease of Integrations

4.9 out of 5 stars

4.9 out of 5 stars on G2

G2 Leader, Spring 2026G2 Fastest Implementation, Spring 2026G2 High Performer, Spring 2026G2 Best Est. ROI, Spring 2026

Put Integrations on Autopilot. Talk to Experts.

Knit is loved by customers across the globe due to our seamless product and white glove support. You'll love us too!

Talk to a Human