> ## 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.

# Deel API Authentication

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

Toku connects to Deel as an authorized [Deel App Store](https://developer.deel.com/docs/authentication) application using Deel's OAuth 2.0 flow. Your Deel admin authorizes the connection once — 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 Deel's consent screen, which lists every scope Toku requests.
  </Step>

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

  <Step title="Refresh">
    Access tokens live for 30 days. Toku rotates them automatically using Deel's single-use refresh tokens — the connection stays live without re-authorization.
  </Step>
</Steps>

Authenticated requests are sent over HTTPS and carry the token as a bearer header alongside Toku's client identifier — Deel requires both:

```bash theme={null}
curl "https://api.letsdeel.com/rest/v2/people" \
  -H "Authorization: Bearer <access_token>" \
  -H "x-client-id: <toku_client_id>"
```

## Scopes

Deel enforces granular scopes in the `{resource}:read` / `{resource}:write` format. Toku requests the minimum set needed for stablecoin payroll:

| Scope               | Access | Used for                                |
| ------------------- | ------ | --------------------------------------- |
| `people:read`       | Read   | Worker roster sync and matching         |
| `worker:read`       | Read   | Worker-level detail for roster sync     |
| `contracts:read`    | Read   | Mapping each worker's active contract   |
| `adjustments:read`  | Read   | Verifying the Toku deduction each cycle |
| `adjustments:write` | Write  | Applying the Toku deduction             |

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

## Environments

| Environment                                  | Base URL                            |
| -------------------------------------------- | ----------------------------------- |
| Production                                   | `https://api.letsdeel.com/rest/v2`  |
| Sandbox (used during implementation testing) | `https://api-sandbox.demo.deel.com` |

<Note>
  Toku is integrated through the [Deel Developer Platform](https://developer.deel.com/) partner process as a Deel App Store application. See [Deel's authentication docs](https://developer.deel.com/docs/authentication) and [OAuth reference](https://developer.deel.com/api/oauth) to validate any of the calls referenced in this section.
</Note>

## Next

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

  <Card title="Payroll Sync" icon="calendar" href="/integrations/deel/payroll-sync">
    How Toku tracks payroll cycles and payslips
  </Card>
</CardGroup>