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

# Rippling API Authentication

> How Toku authenticates with the Rippling REST API using OAuth 2.0 and admin-approved scopes

Toku connects to Rippling as a partner app built in the [Rippling Developer Portal](https://developer.rippling.com/documentation/developer-portal) and published as an App Listing in the Rippling App Shop. Your Rippling admin installs the app once and consents to the declared scopes — no API keys are copied or stored by your team.

## OAuth 2.0 Flow

Rippling uses the standard [OAuth 2.0 authorization-code flow](https://developer.rippling.com/documentation/developer-portal/v2-guides/installation):

<Steps>
  <Step title="Install">
    Your admin installs Toku from the Rippling App Shop and reviews the consent screen, which lists every scope declared on Toku's App Listing.
  </Step>

  <Step title="Exchange">
    Rippling redirects back to Toku with `?code=...`, an authorization code that Toku's backend exchanges for an access token and refresh token.
  </Step>

  <Step title="Refresh">
    Tokens are issued per-company. Toku rotates access tokens automatically using the refresh token — the connection stays live without re-authorization.
  </Step>
</Steps>

Authenticated requests to the Rippling REST API carry the token as a bearer header:

```bash theme={null}
curl "https://rest.ripplingapis.com/workers" \
  -H "Authorization: Bearer <access_token>"
```

## Scopes

Rippling scopes follow a per-resource read/write convention: each scope is declared on Toku's App Listing, shown to your admin at install time, and gates access to the matching endpoints. Toku requests the minimum set needed for stablecoin payroll:

| Resource               | Access | Used for                                     |
| ---------------------- | ------ | -------------------------------------------- |
| Workers                | Read   | Worker roster sync and matching              |
| Compensations          | Read   | Validating election limits against pay       |
| Payroll runs & records | Read   | Pay period and payroll status sync           |
| Earnings inputs        | Write  | Reflecting the Toku pay line item on the run |

Any call outside the approved scopes is rejected by Rippling. You can revoke Toku's installation at any time from your Rippling account, which invalidates the company's tokens.

## Environments

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Production  | `https://rest.ripplingapis.com` |

<Note>
  Toku is integrated through Rippling's partner app process in the [Developer Portal](https://developer.rippling.com/documentation/developer-portal). See the [Rippling REST API documentation](https://developer.rippling.com/documentation/rest-api) to validate any of the calls referenced in this section — note that Rippling's endpoint-level reference requires a Rippling developer sign-in.
</Note>

## Next

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

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