# Gusto HRIS directory sync

<!-- Generated by scripts/generate.ts. Do not edit. -->

Connect your Gusto account in this setup, and we read your employees every few minutes.

:::note[Verification]
Verified on a real Gusto tenant on 2026-11-09.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="connect"></a>

### Connect Gusto

Select Connect Gusto. A page from OhAuthCat names the organization this directory belongs to; check it, then select Continue. Sign in to Gusto as an admin of the company and allow access to read employees. You come back to this setup when Gusto is done.

Only for the `oauth` setup method.

Fixes: [`directory_source_oauth_state_invalid`](/errors/directory_source_oauth_state_invalid/), [`directory_source_oauth_confirm_required`](/errors/directory_source_oauth_confirm_required/)

:::caution[Labels not confirmed in step 1]
The Gusto consent screen labels are not confirmed on a real company account.
:::

</li>

<li class="idp-step">

<a id="choose-company"></a>

### Choose the company

If your Gusto account reaches more than one company, choose the one to sync. Nothing syncs until you choose.

Only for the `oauth` setup method.

Fixes: [`directory_source_company_required`](/errors/directory_source_company_required/)

</li>

<li class="idp-step">

<a id="token"></a>

### Get an API access token

A pasted token is the older option; use Connect Gusto when you can. Get a Gusto API access token for your company that can read employees, from your Gusto developer application or partner contact.

Only for the `token` setup method.

:::caution[Labels not confirmed in step 3]
How a company obtains a long-lived Gusto API token depends on its Gusto developer or partner agreement and is not described on a public page.
:::

</li>

<li class="idp-step">

<a id="company-id"></a>

### Find your company ID

Find your company's UUID in Gusto (company_uuid in the API).

Only for the `token` setup method.

</li>

<li class="idp-step">

<a id="credentials"></a>

### Enter the token and company ID

Enter the access token and company ID. We read your employees once to check them before saving them encrypted; if the check fails, nothing is saved.

Only for the `token` setup method.

Fixes: [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/), [`directory_source_unavailable`](/errors/directory_source_unavailable/)

</li>

<li class="idp-step">

<a id="preview"></a>

### Preview the first sync

Select Preview to see who would be added, updated and removed, without changing anything.

</li>

<li class="idp-step">

<a id="interval"></a>

### Choose how often we read Gusto

We read Gusto every 5 minutes by default. You can set any interval from 5 minutes to 24 hours. After a failure we wait longer between tries, up to an hour.

</li>

<li class="idp-step">

<a id="who"></a>

### Know who is synced

Every sync reads every employee page. Terminated employees and people Gusto no longer returns are removed from the directory, and departments become groups.

</li>

<li class="idp-step">

<a id="reconnect"></a>

### Connect again if access is removed

We keep the connection alive on our own. If Gusto access is revoked or refused, syncs stop with an invalid credentials error; select Connect Gusto again.

Only for the `oauth` setup method.

Fixes: [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/), [`directory_source_unavailable`](/errors/directory_source_unavailable/)

</li>

<li class="idp-step">

<a id="rotate"></a>

### Replace the token when it expires

A pasted token is never refreshed. When it expires, syncs fail with an invalid credentials error; switch to Connect Gusto, or enter a new token.

Only for the `token` setup method.

Fixes: [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/)

</li>

</ol>

## Sources

- [Authentication and authorization (Gusto)](https://docs.gusto.com/embedded-payroll/docs/authentication-and-authorization), read on 2026-10-30
- [Authentication (Gusto app integrations)](https://docs.gusto.com/app-integrations/v2026-02-01/docs/authentication), read on 2026-10-30
