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

# Authentication

> How to authenticate requests, act on another organization and which headers every request carries.

The API uses [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication): your Client ID (`client_id`) is the username and your Secret Key (`client_secret`) is the password. You create credentials for `sandbox` and `production` in the Trio App; see [First API credential](https://docs.trio.com.br/v2/guides/creating-your-first-api-credential.md).

All examples use the sandbox base URL `https://api.sandbox.trio.com.br`.

```bash theme={null}
curl https://api.sandbox.trio.com.br/v2/entities \
  -H "Content-Type: application/json" \
  -u {client_id}:{client_secret}
```

Missing or invalid credentials are refused with `401` and the error code `INVALID_CREDENTIALS`. A key that is not allowed to perform the request, for instance a read-only key sending a write, is refused with `403` and `FORBIDDEN`. See [Error handling](https://docs.trio.com.br/v2/developers/error-table.md).

## Request headers

Besides the credentials, requests carry:

* `Content-Type: application/json` on every request with a body;
* `Trio-Version`: the version of the API the request targets. A request whose header is missing or names a version that is not the current one is refused with `400` and the error code `INVALID_TRIO_VERSION`.

```bash theme={null}
curl https://api.sandbox.trio.com.br/v2/entities \
  -H "Content-Type: application/json" \
  -H "Trio-Version: {trio_version}" \
  -u {client_id}:{client_secret}
```

## Acting on another organization

If your organization has been granted access to another organization, any of your API keys can operate on it by sending the `Trio-Target-Org-Id` header. The credential is the same; the header only changes which organization the request acts on.

* **Header omitted**: the request acts on your own organization.
* **Header present**: the request acts on the target organization. The target ID is validated against your granted access on every request; without access, the request returns `403` with the error code `FORBIDDEN`.

```bash theme={null}
curl https://api.sandbox.trio.com.br/v2/entities \
  -H "Content-Type: application/json" \
  -H "Trio-Target-Org-Id: {target_org_id}" \
  -u {client_id}:{client_secret}
```

> [!NOTE]
>
> Access is granted at the organization level, not per key, and is configured by the Trio team through a channel; it cannot be self-provisioned. Organizations you create through the [Onboarding](https://docs.trio.com.br/v2/api-reference/banking-api/onboarding/create.md) endpoint are typically granted automatically when your channel has API key access enabled: the onboarding response returns the `org_id` to send in this header.
>
> If an access is configured as read-only, only `GET` and `HEAD` requests are allowed on the target organization. Organizations that require mTLS must be reached over your verified channel.

## Next steps

* [Environments](https://docs.trio.com.br/v2/developers/environments.md): sandbox and production base URLs.
* [Error handling](https://docs.trio.com.br/v2/developers/error-table.md): every status code and error code.
* [Request identification](https://docs.trio.com.br/v2/developers/request-identification.md): the `X-Request-Id` to quote when you contact support.


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