---
title: "How do I set up an integration system user and API client…"
description: "Create the integration system user, its security group and permissions, register the API client for integrations, and generate the refresh token, with Workday…"
url: https://kiweely.com/guides/workday-integration-system-user-api-client
---

# How do I set up an integration system user and API client in Workday so an external app can authenticate?

Create the ISU, put it in an Integration System Security Group, grant domain permissions and activate them, register the client for integrations, then generate its refresh token and pick the ISU as the Workday account.

-   **Checked** against Workday on November 19
-   Applies to **Workday Extend**
-   9 min read
-   Published September 22
-   By Kiweely

Create the integration system user (ISU), add it to an Integration System Security Group, give that group permissions on the domains the app calls and activate them, register an API client with Register API Client for Integrations, then generate a refresh token for the client and select the ISU as its Workday account. The app exchanges the Client ID, Client Secret and refresh token for access tokens at the tenant’s token endpoint.

Kiweely Vine is a desktop AI agent for Workday consultants and developers that walks through and uses these API client connections directly in the tenant you connect.

This page is the setup. If you are choosing between Register API Client and Register API Client for Integrations, read [Register API Client vs. Register API Client for Integrations](https://kiweely.com/guides/workday-register-api-client-vs-api-client-for-integrations) first. If setup is done and a call fails, use [ISU and API client errors: 401, invalid\_client, invalid\_grant](https://kiweely.com/guides/workday-isu-authentication-errors).

## What are the steps, in order, with the Workday task for each?

| Step | Workday task | Security domain Workday lists for it |
| --- | --- | --- |
| 1\. Create the ISU | Create Integration System User | Integration Security, Integration functional area |
| 2\. Exempt its password from expiry (user name and password use) | Maintain Password Rules | Not listed in the pages used here |
| 3\. Create the security group and add the ISU | Create Security Group | Security Configuration, System functional area |
| 4\. Grant domain permissions | Maintain Permissions for Security Group | Security Configuration, System functional area |
| 5\. Activate them | Activate Pending Security Policy Changes | Security Configuration, System functional area |
| 6\. Register the client | Register API Client for Integrations | Security Administration, System functional area |
| 7\. Generate the refresh token | Manage Refresh Tokens for Integrations, on the client | Security Administration, System functional area |

Sources: [Set Up Live Data Query ISU Authentication](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-live-data-query-/set-up-live-data-query-isu-authentication.html) for steps 1, 3 and 5, and [Register a Workday Prism Analytics API Client](https://doc.workday.com/admin-guide/en-us/workday-studio/integration-design/common-components/the-prismanalytics-subassembly/tzr1533120600898.html) for steps 6 and 7. The Register API Client task is listed there with Set Up: Tenant Setup - Security and Security Administration.

## How do I create the integration system user?

Open Create Integration System User and complete these fields the way Workday’s own integration procedures do:

-   User Name: unique, and named for the integration, not for the person who set it up.
-   New Password and New Password Verify: set a password.
-   Require New Password at Next Sign In: leave it cleared.
-   Session Timeout Minutes: keep zero, so the session does not expire. Workday notes that an expired session can stop an integration before it finishes.
-   Do Not Allow UI Sessions: select it, so the account cannot sign in through the browser.

If the ISU authenticates with its user name and password, open Maintain Password Rules and add it to the System Users Exempt from password expiration field ([Create Integration System User for Supplier Remittance](https://doc.workday.com/admin-guide/en-us/financial-management/supplier-accounts/supplier-remittance-integration/ctz1496687853525.html)). Workday’s Peakon procedure marks that step optional.

## How do I put the ISU in a security group and give it permissions?

Run Create Security Group and choose the type Integration System Security Group (Unconstrained). Add the ISU in the Integration System Users prompt. For an existing group, Edit Security Group has the same prompt. You can also start from the ISU: on its related actions menu, Security Profile, then Assign Integration System Security Groups.

Workday’s procedures use the unconstrained type for these integrations. A constrained integration system security group exists too: Workday’s custom object security describes it as reaching workers in the organizations the group has access to.

Then grant the group permissions on each domain the app touches. Run Maintain Permissions for Security Group to edit the Domain Security Policy Permissions for the group in one place. For REST, including WQL, the group needs a Report/Task permission: View for GET, Modify for POST, PUT, PATCH and DELETE. Workday says REST requires Report/Task permissions whether the user is an ISU or a person, and that Integration Permissions (Get and Put) apply only to SOAP ([Workday REST API security](https://developer.workday.com/documentation/dan1370797986071/ConceptWorkdayRESTAPISecurity)).

Finally run Activate Pending Security Policy Changes, add a comment, tick Confirm and click OK. Until you do, the policy edit is pending. For Live Data Query, Workday adds that a security group change made after the client connected can take up to 15 minutes to propagate.

Next: [what a pending security change looks like and how to activate it](https://kiweely.com/guides/workday-isu-permissions-activate-pending-security-policy-changes).

## How do I register an API client for integrations?

Open Register API Client for Integrations and complete:

| Field | What to enter |
| --- | --- |
| Client Name | A unique name for this integration |
| Non-Expiring Refresh Tokens | Selected. Workday’s Prism procedure says it is selected automatically and not to clear it |
| Scope (Functional Areas) | The functional area of the API you call |
| Include Workday Owned Scope | Select it when the call needs core Workday domains that belong to no functional area |

Click OK, then save the Client ID and Client Secret from the confirmation page. Workday’s Peakon procedure warns that the secret cannot be recovered once you close the page.

## Which functional areas should I select for the API client scope?

Choose the area of the API, not every area. Workday’s documents give these:

-   WQL from an outside system: System. The account behind the refresh token needs access to execute reports, and the Workday Query Language domain in the System functional area ([Workday Query Language](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/aht1611188422513.html)).
-   Prism Analytics REST and the Studio PrismAnalytics component: Prism Analytics, with Include Workday Owned Scope selected.
-   Data Lake: Data Cloud.
-   Workday’s external agent setup: Agent System of Record, with Include Workday Owned Scope selected.
-   Any other REST endpoint: its description in the REST API Explorer names the securing domain and, beside it, the scope, which is the matching functional area.

A call succeeds only when both agree. The client’s scope has to include the area, and the user the token acts as needs permission on the domain. Missing either returns a refusal; see [403 forbidden: user security vs client scope](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope). More on narrowing the scope: [least-privilege functional areas](https://kiweely.com/guides/workday-api-client-functional-areas-least-privilege-scoping).

## How do I tie the ISU to the API client?

For a refresh-token client, the tie is made when you generate the token. On the registered client’s related actions menu, choose API Client, then Manage Refresh Tokens for Integrations. Select the ISU from the Workday Account field and generate a new refresh token. Record it. Every call the app makes with that token runs as that ISU ([Register API Client for Data Lake (Refresh Token Grant)](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/register-api-client-for-data-lake--refresh-token-g.html)).

You cannot do this step signed in as an ISU. Workday’s Prism procedure says so, so an administrator does it and chooses the ISU in the Workday Account field.

For a JWT Bearer client the tie is different. In the Register API Client task you set Client Grant Type to JWT Bearer Grant, attach an x509 certificate and fill the Integration System User field ([Register API Client for Data Lake (JWT Bearer Grant)](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/register-api-client-for-data-lake--jwt-bearer-gran.html)).

## How does the app get an access token?

The token endpoint is on the tenant host, in this shape: `https://<host>/ccx/oauth2/<tenant>/token`. Find the host and tenant on View API Clients, as in the next section. Workday’s agent setup posts a form-encoded request to its token endpoint for an ISU client, with four parameters:

| Parameter | Value |
| --- | --- |
| `grant_type` | `refresh_token` |
| `refresh_token` | the refresh token you generated |
| `client_id` | the Client ID |
| `client_secret` | the Client Secret |

Workday’s example is for its agent gateway, whose path differs from the tenant’s; the parameters are the standard OAuth refresh-token request ([Connect External Agents to Workday Using A2A](https://doc.workday.com/admin-guide/en-us/workday-ai/agents/external-agents/connect-external-agent-to-workday-using-a2a.html)). The response carries the access token for the Authorization header, and in that example a new refresh token.

## Where do I find the ISU and API client information in Workday?

-   View API Clients shows the Workday REST API Endpoint, which contains the host and tenant name. Its API Clients for Integrations tab lists the integration clients and their Client IDs. Copy the endpoint, drop `https://` at the start and `/ccx/api/v1/<tenant>` at the end to get the host name ([Obtain the Workday REST API Endpoint](https://doc.workday.com/admin-guide/en-us/workday-studio/integration-design/common-components/the-prismanalytics-subassembly/qjw1533213809425.html)).
-   View Integration System lists the integration systems in the tenant. From an integration system’s related actions menu, Workday Account, then Edit, shows which ISU it runs as.
-   View Security Groups for User lists the security groups assigned to a user, and Workday’s own troubleshooting uses it on an ISU’s group setup (domain Security Activation, System functional area).
-   The Client Secret and the refresh token are shown when created. The Client Secret cannot be recovered afterwards, so generate a new secret or a new token rather than looking for the old value.

## Who can see the ISU and API client configuration?

Workday ties each task to a security domain. The procedures used for this page list:

-   View API Clients and Register API Client for Integrations: Security Administration, System functional area.
-   Create Integration System User: Integration Security, Integration functional area.
-   Create Security Group and Activate Pending Security Policy Changes: Security Configuration, System functional area.

Workday gates each task on its domain, so an administrator needs the matching domain permission through their own security group to run it. To keep ISU and client details narrow, give those domains only to the administrators who set up integrations, and check who holds them in the Domain Security Policy for each. For the user-versus-client side of access, see [who can launch an integration](https://kiweely.com/guides/workday-who-can-launch-integration).

## Worked example: a read-only WQL client

Goal: an external reporting app reads worker counts with WQL.

1.  Create Integration System User: user name `isu_wql_reader`, Do Not Allow UI Sessions selected, Session Timeout Minutes zero.
2.  Create Security Group: type Integration System Security Group (Unconstrained), name `ISSG WQL Readers`, with `isu_wql_reader` in Integration System Users.
3.  Maintain Permissions for Security Group: View on the Workday Query Language domain and on the domains behind the fields it will query.
4.  Activate Pending Security Policy Changes.
5.  Register API Client for Integrations: name `WQL Reader`, Non-Expiring Refresh Tokens selected, scope System. Save the Client ID and Client Secret.
6.  Manage Refresh Tokens for Integrations on `WQL Reader`: Workday Account `isu_wql_reader`, generate, record the token.
7.  Exchange the token, then call `GET https://<host>/ccx/api/wql/v1/<tenant>/dataSources?limit=1`.

In Workday’s Development tenant, a client with scope System returned HTTP 200 on that call, with `"total":1689` data sources. On the same client, `GET .../common/v1/<tenant>/workers?limit=1` returned HTTP 403 with this body:

```
{"error":"permission denied","code":"S22","severity":"Critical"}
```

That refusal is what a call looks like when the client’s scope or the user’s domain permission does not cover the endpoint. The WQL call passed because the scope and the user’s permissions covered it.

## What the setup is not

A client alone gives no data access, and neither does an ISU alone. The ISU supplies the identity and its security group supplies permissions, and the client supplies the scope and the credentials. Workday evaluates all three on every call.

## Watch Kiweely Vine connect with an API client for integrations

![Register API Client for Integrations in Workday, as Kiweely Vine connects to a Development tenant](https://kiweely.com/guides/workday-integration-system-user-api-client/media/vine-api-client-for-integrations-3975d1106e74.webp)

From the film: Register API Client for Integrations in Workday.

In one recorded session against a Workday Development tenant, Kiweely Vine explains each way to connect it to Workday and what to register. A consultant registers an API client and an API client for integrations, generates the client secret and a refresh token, and connects Vine with them.

[Watch the film (11 min)](https://www.youtube.com/watch?v=K_9xp_OImGE) · [Pricing](https://kiweely.com/pricing) · [Start free](https://kiweely.com/download)

## Sources checked

-   [Set Up Live Data Query ISU Authentication in Workday](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-live-data-query-/set-up-live-data-query-isu-authentication.html)
-   [Register API Client for Data Lake (Refresh Token Grant)](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/register-api-client-for-data-lake--refresh-token-g.html)
-   [Register API Client for Data Lake (JWT Bearer Grant)](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/register-api-client-for-data-lake--jwt-bearer-gran.html)
-   [Set Up Integration System Users for Data Lake](https://doc.workday.com/admin-guide/en-us/workday-data-cloud/data-out/workday-data-lake/set-up-isus-for-data-lake.html)
-   [Register a Workday Prism Analytics API Client](https://doc.workday.com/admin-guide/en-us/workday-studio/integration-design/common-components/the-prismanalytics-subassembly/tzr1533120600898.html)
-   [Obtain the Workday REST API Endpoint](https://doc.workday.com/admin-guide/en-us/workday-studio/integration-design/common-components/the-prismanalytics-subassembly/qjw1533213809425.html)
-   [Create Integration System User for Supplier Remittance](https://doc.workday.com/admin-guide/en-us/financial-management/supplier-accounts/supplier-remittance-integration/ctz1496687853525.html)
-   [Steps: Set Up Workday Integration (Peakon)](https://doc.workday.com/peakon/en-us/workday-peakon-employee-voice/integrations/workday-integration/qdk1635869479224.html)
-   [Connect External Agents to Workday Using A2A](https://doc.workday.com/admin-guide/en-us/workday-ai/agents/external-agents/connect-external-agent-to-workday-using-a2a.html)
-   [Workday Query Language (WQL)](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/aht1611188422513.html)
-   [Workday REST API security](https://developer.workday.com/documentation/dan1370797986071/ConceptWorkdayRESTAPISecurity)

## Related guides

[All guides](https://kiweely.com/guides)

### More guides on Integrations and APIs

[All 89 guides](https://kiweely.com/guides#integrations)

-   [What is the safest way to copy Workday configuration from one tenant to another?](https://kiweely.com/guides/workday-configuration-between-tenants)
-   [Multi-Tenant FDE Access via Customer Central Manage Tenant Access](https://kiweely.com/guides/multi-tenant-fde-customer-central-access)
-   [Configuration Catalog migrate blocked: fix the first 50 Object Transporter prerequisites](https://kiweely.com/guides/configuration-catalog-prerequisites-blocking)
-   [Why the same account ID across tenants unlocks Object Transporter](https://kiweely.com/guides/workday-customer-central-same-account-id)
-   [Tenant Compare after Object Transporter: when and how to run it](https://kiweely.com/guides/workday-tenant-compare-after-migration)
-   [How to find what Object Transporter can migrate](https://kiweely.com/guides/workday-object-transporter-supported-objects)
-   [Permission to launch a Workday integration: which domains Studio checks](https://kiweely.com/guides/permission-to-launch-workday-integration)
-   [What Workday Customer Central is (and isn’t) for implementers](https://kiweely.com/guides/workday-customer-central-for-implementers)

### From the blog on Integrations and APIs

[All posts](https://kiweely.com/blog)

-   [What Is an AI-Built Workday Integration Platform Outside the Tenant?](https://kiweely.com/blog/what-is-ai-built-workday-integration-platform)
-   [Nothing Kept After a Run: Zero-Retention Workday Integrations](https://kiweely.com/blog/nothing-kept-after-a-run-zero-retention-integrations)
-   [Retire Workday Studio and EIB Debt with External Integrations](https://kiweely.com/blog/retire-workday-studio-eib-debt-with-external-integrations)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
