> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taxrock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> OAuth 2.0 Authorization Code with PKCE, refresh tokens, and reconnects.

Delegate access uses OAuth 2.0 **Authorization Code with PKCE**. A TaxRock user connects your
application once, by logging in to TaxRock and consenting. Your backend ends up holding a
long-lived **refresh token** per connected user, which it exchanges for short-lived **access
tokens** to call the API on that user's behalf. See the [Quickstart](https://docs.taxrock.com/delegate-access/quickstart.md)
for the concrete commands. This page covers the model and steady-state behavior.

## Callback URL

After consent, TaxRock redirects the user to the callback URL registered for your application in
that environment. Send us your callback URL for each environment so we can register it.

## 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`](https://docs.taxrock.com/delegate-access/api-reference/authentication/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](https://docs.taxrock.com/delegate-access/api-reference/authentication/token.md) 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](https://docs.taxrock.com/delegate-access/api-reference/authentication/token.md).

**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](#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.

## Scopes

Two scopes gate the API, and the user consents to them at the authorize step:

* **`read:client-accounts`**: the [compliance lookups](https://docs.taxrock.com/api-reference/lookup-results.md) and the
  [transcript endpoints](https://docs.taxrock.com/api-reference/transcripts/overview.md).
* **`verify:tins`**: [TIN verification](https://docs.taxrock.com/api-reference/tin-match-results.md).

Request the scopes you need, plus `offline_access` (which yields the refresh token), in
the authorize URL's `scope` parameter. A connection's tokens carry only the scopes its
consent requested, and **refreshing never adds scopes**: a refresh token issued before
`verify:tins` existed can't gain it. Existing connections keep working unchanged; to
start using TIN verification on one, send the user back through the authorize step
requesting both scopes, and use the new refresh token from that consent.

## 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` means the refresh token expired or was revoked. Send
the user back through the authorize step and surface a **"Reconnect TaxRock"** action.

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`; for TIN
  verification, `verify:tins`). 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 it.

> [!NOTE]
>
> 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](https://datatracker.ietf.org/doc/html/rfc7636).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.