Gusto API Authentication

Toku connects to Gusto as an authorized application using Gusto’s OAuth 2.0 flow. Your Gusto admin signs in once to authorize the connection — no API keys are copied or stored by your team.

OAuth 2.0 Flow

Authorize

From the Toku dashboard, your admin is redirected to Gusto’s consent screen, which lists every scope Toku requests.

Exchange

Gusto redirects back with an authorization code, which Toku’s backend exchanges for an access token and refresh token.

Refresh

Access tokens are short-lived. Toku rotates them automatically using the refresh token — the connection stays live without re-authorization.

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

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`

Toku is integrated through the Gusto Developer Portal partner process, including Gusto’s security review. See Gusto’s API documentation to validate any of the calls referenced in this section.

Employee Sync

How Toku reads your employee roster

Payroll Sync

How Toku tracks pay periods and payroll status

​OAuth 2.0 Flow

​Scopes

​Environments

​Next

Employee Sync

Payroll Sync

OAuth 2.0 Flow

Scopes

Environments

Next