Which token flow: tenant API client or Developer Site API client

Which steps you follow in Postman depends on where the API client was created. A client registered in the tenant with the Register API Client for Integrations task gets its token from the tenant's own token endpoint, usually by exchanging a refresh token generated for an integration system user. A client created in the Console on the Workday Developer Site (the Extend route) gets its token from Workday's authorization service at auth.api.workday.com, through a user sign-in or client credentials.

Both end the same way: an access_token that you send as Authorization: Bearer <token> on every REST or Graph API request.

Route 1: a tenant API client with a refresh token

This is the usual route for testing REST or WQL calls the way an integration will make them, as an integration system user (ISU).

Set it up in the tenant

  1. Run Register API Client for Integrations. Give the client a name and pick the Scope (Functional Areas) the endpoints need; the REST API Explorer lists the scope on each endpoint. For WQL, Workday's guide says to select System. Select Non-Expiring Refresh Tokens if you want the refresh token to keep working between test sessions, and Include Workday Owned Scope where the API requires it.
  2. Save the Client ID and Client Secret. The token endpoint has the form https://{host}/ccx/oauth2/{tenant}/token. If you do not know the host, the View API Clients report lists the tenant's Workday REST API Endpoint, which starts with it.
  3. From the client's related actions, choose API Client > Manage Refresh Tokens for Integrations, select the ISU in Workday Account, and save the refresh token from the confirmation page.

The account you pick here is the account every call runs as. Workday's WQL guide makes the point directly: select a Workday account that has access to what the calls need, because the API calls use that account.

Build the token request in Postman

Create a POST request to the token endpoint:

POST https://{host}/ccx/oauth2/{tenant}/token
  • Authorization tab: Basic Auth, with the client ID as the username and the client secret as the password. Workday's administrator guide uses the same username and password pair for requests to this tenant token endpoint.
  • Body tab: x-www-form-urlencoded, with grant_type = refresh_token and refresh_token = the token you saved.

Send it. The response contains access_token and token_type Bearer. To avoid pasting the token by hand, add a test script to the token request:

pm.collectionVariables.set("wdToken", pm.response.json().access_token);

Then set the collection's Authorization to Bearer Token with {{wdToken}}, and every request in it uses the latest token.

Call an API with it

Tenant clients call the REST APIs on the tenant host:

GET https://{host}/api/staffing/v7/{tenant}/workers?limit=5
Authorization: Bearer {{wdToken}}

That path shape, /api/{service}/{version}/{tenant}, is the integrations base path from Workday's REST fundamentals. It is different from the API gateway path in route 2: a tenant client's token goes with the tenant host path, and a Developer Site client's token with the gateway.

Route 2: a Developer Site client with Postman's OAuth 2.0 helper

Clients created under Console > API Clients on the Developer Site use Workday's authorization service. Workday documents these endpoints for the United States region:

  • Authorization endpoint https://auth.api.workday.com/v1/authorize
  • Token endpoint https://auth.api.workday.com/v1/token

Other regions use their own authorization base URL, such as https://api.eu.wcp.workday.com/auth, and personal developer accounts use https://api.odp.wcp.workday.com/auth. Your account's gateway is listed on your Developer Site profile. Calling a gateway outside your account's region can return 401: Unauthorized.

Authorization code flow in Postman

  1. On the API client, add Postman's callback URL as a Redirect URI. If you use Postman's browser authorization, that is https://oauth.pstmn.io/v1/callback.
  2. In Postman's Authorization tab, choose OAuth 2.0 and fill in: Grant Type Authorization Code (or Authorization Code with PKCE, which Workday also supports), the Auth URL and Access Token URL above, and the client ID and client secret.
  3. Click Get New Access Token. Workday asks for the tenant alias, then shows the tenant's sign-in page. Sign in as the user the calls should run as.
  4. Use the token on requests to the API gateway, for example GET https://api.workday.com/staffing/v7/workers.

Workday's token examples for this service send the client credentials as Authorization: ID <Base64 of ClientID:ClientSecret>, not the plain Basic header Postman's helper builds. If the helper's token exchange is rejected, send the token request yourself as a POST with that header and the authorization_code form body Workday documents.

Workday also documents a tenantAlias=yourTenant parameter on the authorization endpoint, which supplies the alias so the user is not asked for it. If the tenant redirects to a single sign-on provider you have no account in, Workday's authorization flows page documents redirect=n on the authorization endpoint to sign in to the tenant directly.

Client credentials for a service account

If the calls should run as an ISU without a sign-in, Workday's client credentials flow maps the client to an ISU in the tenant with Create Client Credentials Mapping. In Postman, POST to the token endpoint with the header Authorization: ID <Base64 of ClientID:ClientSecret> (no space after the colon inside the encoded value) and a form body of grant_type = client_credentials and tenant_alias = your tenant alias. The ISU is the subject of the token, and the client needs the scope for the endpoint while the ISU needs the domain permissions.

Token lifetime and refreshing

Workday states that Extend access tokens expire after 60 minutes, and its authorization code pages also tie the token timeout to the session timeout set for the user. When a token expires, request a new one. With a refresh token, Workday returns a new access token and a new refresh token; for Developer Site clients, the refresh timeout set on the client runs from the first authorization and is not extended by refreshing.

A refresh token belongs to the user who authorized it. Workday warns that if that user's username changes or the user is deactivated, the refresh token stops working, which is the usual cause when a Postman collection that worked last month now fails at the token step.

Prove the token works

Call something small and specific to the account, such as GET .../workers/me for a user token, or a one-row WQL query for an ISU token. A 200 proves the token, endpoint and scope line up. A 401 points at the token or the base URL; a 403 means the token is fine but the account lacks the domain permission or the client lacks the scope, which the ISU authentication errors guide works through. For the ISU and API client setup itself, see setting up a Workday integration system user and API client.

When you move to a non-development tenant, a Developer Site client must be allowed on that tenant; only a Company Administrator can add it with Modify Authorized Tenants.

Sources checked