OAuth 2.0 and refresh tokens for third-party APIs in Workday Orchestrate, using the Workday credential store

Put the OAuth client in the credential store, not in the orchestration

For a third-party API that uses OAuth 2.0, the supported pattern is: register the client in the tenant with the Create External Client CredStore task, then create an OAuth credential of type Cred Store Reference in the orchestration's Settings and select it on the Send HTTP Request step. The credential's Client Authentication setting decides whether the client credentials go to the token endpoint in the request header or the body, so the orchestration's own steps never handle the secret. Workday's Create Orchestration Credentials page recommends always using the Cred Store Reference option in Production.

Workday's Create External Client CredStore page states the purpose directly: the task lets external apps and orchestrations store OAuth 2.0 access and refresh tokens in the Workday credential store. The client secret and tokens stay in the tenant; the app source holds only a reference ID.

This is for calls to other systems. Calls to Workday itself go through Send Workday API Request, whose authentication comes from the app's own credential (the initiating user's access token or an ISU). Workday's Orchestrate course manual is explicit that you should not add OAuth headers to Workday API calls by hand.

Which OAuth grant you can use

The credential store's Auth Scheme for External Client field determines the grant. These are the values Workday's pages use:

Prefer client credentials for anything scheduled or launched by an integration event. There is no user present to renew consent, and there is no refresh token to lose.

The authorization code grant is where refresh tokens come in, and it is the least documented path for orchestrations. Workday describes user consent only for Extend pages: the oauthButton and oAuthLoginButton tags prompt the user and call the provider, with the client registered in the credential store. Neither the Create Orchestration Credentials page nor the orchestration templates describe a consent step or say how a Cred Store Reference credential uses a stored user's refresh token. If the API offers client credentials, use them; if it only offers authorization code, prove in a sandbox that a scheduled run still authenticates after the provider's access-token lifetime has passed before you commit to the design.

Step 1: Create the External Client CredStore in the tenant

Run Create External Client CredStore in the tenant where the orchestration runs. It needs the Security Administration domain in the System functional area. The fields, from Workday's page:

• App ID: the reference ID of the app that launches the orchestration, including its postfixed account ID (as shown in App Manager or the app's AMD).
• External Reference ID: a unique value you choose, for example acmeTicketingOauth. The orchestration refers to the credential by this ID.
• Client ID and Client Secret: from the third party's client registration.
• Token Endpoint: the provider's OAuth 2.0 token URL.
• Authorization Endpoint: needed for the authorization code grant; leave it empty for client credentials.
• Scope: whatever scope the provider requires.
• Auth Scheme for External Client: as in the table above.

The Workday-documented setup for Microsoft agent sync is a clean client-credentials example: Auth Scheme for External Client set to OAuth 2.0 Client Credential, the service principal's client ID and secret, and the Microsoft identity platform token endpoint.

Create the store in each tenant the app runs in, each with the client registration meant for that environment, so a sandbox run never calls the provider's production account. This is a recommended setup rather than a documented rule.

Step 2: Reference it from the orchestration

In Orchestration Builder, open the orchestration's Settings, choose the Credentials tab, and add a credential:

1. Credential Name: the name you will pick on the step.
2. Type: OAuth.
3. OAuth type: Cred Store Reference.
4. Reference: the External Reference ID from step 1.
5. Client Authentication: whether the request carries the client credentials in the header or the body. Match what the provider's token endpoint accepts: HTTP Basic in the header (client_secret_basic) or form fields in the body (client_secret_post).

Then on each Send HTTP Request step that calls the API, open the Auth tab and select the credential. Workday's Extend Orchestration Toolkit sample (OAuthCCExample) is exactly this: an OAuth credential whose token is a credential store reference, selected as the auth of one Send HTTP Request to a third-party URL.

The other OAuth type, Token, takes a literal token and scheme. Use it only for a quick test against a development tenant: the token is in the app definition and nothing renews it.

Rotating secrets without an outage

Workday's guidance on the Create Orchestration Credentials page is to update credentials in the credential store at least a week before they expire and to keep both the old and the new valid during that overlap. In practice:

1. Create a second client secret at the provider, if it allows two active secrets per client.
2. Update the External Client CredStore with the new secret while the old one still works.
3. Run the integration once and confirm the calls succeed.
4. Revoke the old secret at the provider.

Because the orchestration only knows the reference ID, none of this needs an app change or a redeploy.

Why not fetch and refresh tokens yourself

You can call a token endpoint with Send HTTP Request, read access_token from the response and set an Authorization: Bearer header on the next call. For a third-party API with refresh tokens, building it yourself creates two problems the credential store already solves.

First, the client secret and refresh token have to live somewhere the orchestration can read. App attributes (read with attrstore.stringValue(...)) and launch parameters are configuration values, not a secret store, and an orchestration cannot write them back.

Second, providers that rotate refresh tokens return a new one on every refresh and invalidate the old. A hand-built flow has nowhere documented to persist the new token, so the next run fails with the provider's invalid_grant error. Keeping those tokens is the stated job of the External Client CredStore.

Prove it works, and recognise the failures

Run the orchestration in the sandbox and check the HTTP step's response code. Give the step a retry policy with a 200–299 success range so a 401 actually fails the run; without one, Workday's retry page notes an unsuccessful response does not fail the orchestration (see HTTP retries and polling).

If the call fails, read the provider's error before changing anything in Workday:

• 401 or invalid_client from the provider: wrong client ID or secret, or the wrong Client Authentication choice (header versus body).
• invalid_scope: the Scope on the credential store does not match what the client is allowed.
• Works in the sandbox, fails in production: the production tenant has no store with that External Reference ID, or it holds the sandbox client's details.
• Token accepted, data call returns 403: authentication succeeded; the client lacks permission on the provider's side.

Repeat the test after each secret rotation, before revoking the old secret.