Skip to main content

Workday

Workday HCM: agents read workers, organizations and jobs through your tenant's REST API, as an integration user.

Connect it with: Service account. Workday's own documentation: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html.

What agents can do​

Connect Workday so the agents working your tasks can reach it. With it connected, they can:

  • Look up workers: names, positions, managers, locations and organizations.
  • Read the organization structure, supervisory organizations and job profiles.
  • Read time off balances and requests, where the integration user's security groups allow it.
  • Answer questions about headcount and reporting lines, or prepare data for another system.

Before you start​

  • A Workday administrator who can run the tasks Register API Client for Integrations and Create Integration System User.
  • An integration system user (ISU) in a security group whose domain policies cover what agents should see - for example Worker Data: Public Worker Reports. After changing policies, run Activate Pending Security Policy Changes.
  • Your tenant's REST API endpoint, from the View API Clients report.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Workday​

Jaah connects to Workday with a service account, not with a sign-in button.

Connect with an API key​

Find each value first:

  • Workday host: The host name of your tenant's REST endpoint. In Workday, run the View API Clients report: the Workday REST API Endpoint is shown at the top, for example https://wd2-impl-services1.workday.com/ccx/api/v1/acme - enter only the host part (wd2-impl-services1.workday.com).
  • Tenant name: The last part of the same REST API Endpoint (acme in the example above); it is also the name after the host when you sign in to Workday.
  • Client ID: In Workday, run the task Register API Client for Integrations: name the client Jaah, tick Non-Expiring Refresh Tokens, add the functional-area scopes agents need (for example Staffing and Organizations and Roles), and select OK. The Client ID is shown on the confirmation page and later in View API Clients.
  • Client secret: Shown once, on the same confirmation page as the Client ID, right after you register the API client. If you lost it, open the client from View API Clients and choose API Client > Generate New Client Secret.
  • Refresh token: In View API Clients, open the API Clients for Integrations tab, select the Jaah client's related actions and choose API Client > Manage Refresh Tokens for Integrations. Pick the integration system user agents act as, tick Generate New Refresh Token, select OK and copy the token.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Workday card.
  2. Name the secret and choose who can use it.
  3. Fill in Workday host, Tenant name, Client ID, Client secret, Refresh token.
  4. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Not used: Jaah connects to Workday with a service account, not through an OAuth app.

Test the connection​

Select Test on the secret. Jaah checks that each value has the right shape, but does not call Workday: the result reads Format checked — Workday was not called. The first real check is when an agent uses it.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A key connection hands the agent its fields: host, tenant, client_id, client_secret, refresh_token.

Tell the agent in your task description which secret to use, for example “use the Workday secret org/workday”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Workday once the test passes. Steps: Replace or delete a secret.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Workday's side too, delete the service account's key in its cloud console.

Limitations​

  • There is no one-click Connect Workday: Workday registers API clients inside each customer's own tenant (https://community.workday.com/sites/default/files/file-hosting/restapi/index.html), so an administrator registers the Jaah client in your tenant and pastes its values here.
  • Test checks the format of each value and that the host is a public Workday address, but does not call Workday: minting an access token from the refresh token is the first real check, when an agent uses it.
  • Agents get access tokens from your tenant's token endpoint (https://HOST/ccx/oauth2/TENANT/token) using the client ID, client secret and refresh token, and see only what the integration user's security groups allow.
  • Implementation (sandbox) and production tenants have different hosts and clients; connect each one as its own secret.
  • Agents can do only what the connected Workday service account and its roles allow.

Troubleshooting​

Test says Workday host is not in the format Workday uses

Enter only the host name from the REST API Endpoint, such as wd2-impl-services1.workday.com - no https://, no /ccx/... path and no tenant name. Workday hosts end in workday.com or myworkday.com.

An agent reports invalid_client or invalid_grant from the token endpoint

The client secret or refresh token does not belong to this client, or the refresh token was regenerated or revoked. In Workday, open the client from View API Clients, generate a new refresh token with Manage Refresh Tokens for Integrations, and select Replace on the secret.

An agent's calls succeed but return no workers, or answer 403

The integration system user's security group lacks the domain policy for that data, or the API client lacks the functional-area scope. Add the policy (and run Activate Pending Security Policy Changes) or edit the API client's scopes, then ask the agent to try again.

Still stuck? Select Test and read the result: it names the first value that is missing or not in the shape Workday uses. It does not call Workday, so Workday's own errors show only in the agent's session.

FAQ​

Why is there no Connect Workday button?

Workday has no shared sign-in for outside apps: each company registers API clients inside its own tenant. Registering a client for integrations gives a refresh token that does not expire, which works like a key.

Which user do agents act as?

The integration system user you chose when generating the refresh token. Use a dedicated ISU for Jaah so its access can be reviewed and revoked on its own.

How do I revoke Jaah's access in Workday?

Open the Jaah client from View API Clients and choose API Client > Manage Refresh Tokens for Integrations to revoke the token, or deactivate the API client. Agents lose access when their current access token expires.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Workday account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.