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

> The client credentials grant, access tokens, and what a credential reads.

Direct access uses the OAuth 2.0 **client credentials** grant. Your backend exchanges its
`client_id` and `client_secret` for an access token, and sends the token as a `Bearer` credential.
See the [Quickstart](https://docs.taxrock.com/direct-access/quickstart.md) for the concrete commands.

## What a credential reads

Every response returns the data of the organization the credential was issued for. Requests never
name an organization, and responses never identify one. To read several organizations, hold one
credential for each.

## Tokens

* Get an access token from [Get a token](https://docs.taxrock.com/direct-access/api-reference/authentication/token.md) with
  `grant_type` `client_credentials`, your `client_id` and `client_secret`, and `audience`
  `https://api.taxrock.com` (the same in both environments).
* **Cache the access token and reuse it until it expires.** `expires_in` gives its lifetime in
  seconds. Request a new token when the cached one expires, not once per call.
* There is no refresh token. When a token expires, request a new one the same way.
* Keep the `client_secret` on your backend. Never send it to a browser or a mobile app.

## Errors

* **`401`**: the access token is missing, invalid or expired. Get a new token.

* **`403`** with `error` `forbidden`: the credential is not set up for direct access. A new token
  will not fix it. Contact TaxRock.

  ```json theme={null}
  { "error": "forbidden", "message": "This client is not authorized for direct access." }
  ```

* **`404`** with `error` `not_found`: the taxpayer or transcript does not exist, or it is outside
  the credential's organization.

* **`400`** with `error` `invalid_request`: a malformed `id`, `page` or `pageSize`.


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