Skip to main content
The Delegate API uses OAuth 2.0 Authorization Code with PKCE. Your backend ends up holding a long-lived refresh token per end-user, which it exchanges for short-lived access tokens to call the API. See the Quickstart for the concrete commands. This page covers the model and steady-state behavior.

​
The flow

1

Authorize (one-time, interactive)

Generate a code_verifier and its code_challenge (PKCE, S256), and keep the verifier for the next step. Send the user to the /authorize URL with that code_challenge and a state value you generate. They log in to TaxRock and consent, and TaxRock redirects to your registered callback with ?code=...&state=.... Verify the returned state matches what you sent.
2

Exchange the code (backend)

Call Get or refresh a token with the code, code_verifier, and client_secret (the authorization_code grant) to receive an access_token and a refresh_token. Store the refresh token securely, per end-user.
3

Refresh (steady state)

When a cached access token has expired, exchange the refresh token for a fresh access token. See Get or refresh a token.
4

Reconnect (as needed)

Refresh tokens eventually expire and can be revoked. When a refresh returns invalid_grant, send the user back through the authorize step to grant consent again, which issues a new refresh token. See When a user must reconnect.

​
Tokens

  • Access token. Short-lived, about an hour. Cache and reuse it rather than minting one per request. Send it as a Bearer credential.
  • Refresh token. Non-rotating, so keep using the same one. The refresh response returns no new refresh token. It expires after about 100 days idle, with an absolute maximum lifetime of about 365 days, after which the user must reconnect even if active.

​
When a user must reconnect

A refresh that returns invalid_grant, or an API response of 401, means that user’s connection is broken. invalid_grant happens when the refresh token expired: it sat idle past ~100 days, reached its ~365-day maximum, or was revoked. Send the user back through the authorize step and surface a “Reconnect TaxRock” action. This is normal steady-state behavior, not an error to alarm the user with. A 403 from the API is different. Its error field says which kind:
  • insufficient_scope: the access token is missing a required scope. Re-run the authorize step requesting it (for the lookups, read:client-accounts). This is a setup issue, not a broken connection.
  • forbidden: the connected user is not eligible or lacks permission, for example when the TaxRock account is not active or the user’s role does not grant API access. Reconnecting will not fix this, so treat it as an account or configuration issue.
We will give advance notice if a change ever requires re-consent (for example, a new scope).

​
PKCE

For more on generating the code_challenge and code_verifier, see RFC 7636.