> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gusto API Authentication

> How Toku authenticates with the Gusto API using OAuth 2.0 and granular scopes

Toku connects to Gusto as an authorized application using [Gusto's OAuth 2.0 flow](https://docs.gusto.com/app-integrations/docs/introduction). Your Gusto admin signs in once to authorize the connection — no API keys are copied or stored by your team.

## OAuth 2.0 Flow

<Steps>
  <Step title="Authorize">
    From the Toku dashboard, your admin is redirected to Gusto's consent screen, which lists every scope Toku requests.
  </Step>

  <Step title="Exchange">
    Gusto redirects back with an authorization code, which Toku's backend exchanges for an access token and refresh token.
  </Step>

  <Step title="Refresh">
    Access tokens are short-lived. Toku rotates them automatically using the refresh token — the connection stays live without re-authorization.
  </Step>
</Steps>

```bash theme={null}
# Token exchange (performed by Toku's backend)
curl -X POST https://api.gusto.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "<toku_client_id>",
    "client_secret": "<toku_client_secret>",
    "code": "<authorization_code>",
    "grant_type": "authorization_code"
  }'
```

Authenticated requests carry the token as a bearer header and pin a dated API version:

```bash theme={null}
curl https://api.gusto.com/v1/companies/<company_id>/employees \
  -H "Authorization: Bearer <access_token>"
```

## Scopes

Gusto enforces granular, per-resource scopes. Toku requests the minimum set needed for stablecoin payroll:

| Scope                | Access | Used for                                |
| -------------------- | ------ | --------------------------------------- |
| `companies:read`     | Read   | Company and pay schedule details        |
| `employees:read`     | Read   | Employee roster sync and matching       |
| `payrolls:read`      | Read   | Pay period and payroll status sync      |
| `garnishments:read`  | Read   | Verifying the Toku deduction each cycle |
| `garnishments:write` | Write  | Applying the Toku deduction             |

Any call outside these scopes is rejected by Gusto. You can revoke Toku's authorization at any time from your Gusto account, which immediately invalidates all tokens.

## Environments

| Environment                               | Base URL                     |
| ----------------------------------------- | ---------------------------- |
| Production                                | `https://api.gusto.com`      |
| Demo (used during implementation testing) | `https://api.gusto-demo.com` |

<Note>
  Toku is integrated through the [Gusto Developer Portal](https://dev.gusto.com/) partner process, including Gusto's security review. See [Gusto's API documentation](https://docs.gusto.com/) to validate any of the calls referenced in this section.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Employee Sync" icon="users" href="/integrations/gusto/employee-sync">
    How Toku reads your employee roster
  </Card>

  <Card title="Payroll Sync" icon="calendar" href="/integrations/gusto/payroll-sync">
    How Toku tracks pay periods and payroll status
  </Card>
</CardGroup>