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)

Send the user to the /authorize URL. They log in to TaxRock and consent to read:client-accounts, and TaxRock redirects to your registered callback with ?code=.... Generate the code_challenge from a code_verifier (PKCE, S256) and keep the verifier for the next step.
2

Exchange the code (backend)

POST the code, code_verifier, and client_secret to the token endpoint 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.

​
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.
  • audience — an access token is only valid for the audience it was requested for, so include audience on the refresh call.
Refresh
curl -X POST https://login-demo.taxrock.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "audience": "https://delegate.api.taxrock.com"
  }'

​
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: the connected user lacks the required permission, which re-consent will not fix, so treat it as a configuration issue rather than a reconnect.
We will give advance notice if a change ever requires re-consent (for example, a new scope). Watch the Changelog.

​
PKCE

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