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

# Agent Authentication

> How an AI agent obtains and uses Clara API credentials: discovery, registration, token exchange, errors, and revocation.

Clara API authenticates with two layers, and both are required on every request:

1. **mTLS** — an X.509 client certificate issued by Clara.
2. **OAuth 2.0 Bearer token** — a JWT from `/oauth/token`, obtained with `client_id` + `client_secret`.

This page is written for agents. It documents what exists today and states plainly what does **not** exist, so an agent does not burn attempts on endpoints that were never published.

## Discover

Read these resources in this order:

| Resource | URL | What you get |
| - | - | - |
| OpenAPI 3.1 | [`/openapi.json`](https://developers.clara.team/openapi.json) | Every operation, request/response schema, and server URL |
| API catalog | [`/.well-known/api-catalog.json`](https://developers.clara.team/.well-known/api-catalog.json) | Machine-readable index of the API, auth, sandbox, and docs |
| Agent instructions | [`/agent-instructions`](https://developers.clara.team/agent-instructions) | When to use Clara, which interface, safety rules |
| This page | [`/auth.md`](https://developers.clara.team/auth.md) | The credential walkthrough |

Every market has its own host and its own token endpoint:

| Market | Base URL | Token endpoint |
| - | - | - |
| Mexico | `https://public-api.mx.clara.com` | `https://public-api.mx.clara.com/oauth/token` |
| Brazil | `https://public-api.br.clara.com` | `https://public-api.br.clara.com/oauth/token` |
| Colombia | `https://public-api.co.clara.com` | `https://public-api.co.clara.com/oauth/token` |

Credentials are issued per market: use the host that matches the company's market.

**Not published today (as of October 2026):** Clara does not serve RFC 9728 protected-resource metadata at `/.well-known/oauth-protected-resource`, and does not serve RFC 8414 authorization-server metadata at `/.well-known/oauth-authorization-server`. Both return `404` in every market. Do not probe for them, and do not assume a `/.well-known/openid-configuration`. This page is the discovery document.

There is also no `identity_endpoint` to look up, and no `WWW-Authenticate` header on errors that would point at one. Everything an agent needs to authenticate is on this page and in `/openapi.json`.

## Pick a method

Clara supports exactly one identity type.

| Method | Status | Notes |
| - | - | - |
| `service_auth` — OAuth 2.0 client credentials over mTLS | **Supported** | The only way to call the API today |
| `agent_auth` — self-registration through an `identity_endpoint` | **Not supported** | Clara has no agent registration surface |
| `identity_assertion` — ID-JAG (`id-jag`) token exchange | **Not supported** | Clara does not accept assertion grants |

The consequence for an agent is simple: **you cannot mint your own credentials.** A human with Clara platform access creates an API project, and the credentials are handed to the agent out of band. Authorization is granted to that project, not to an agent identity.

## Register

Registration is a dashboard action, not an API call. A human administrator does it:

1. Sign in to the Clara dashboard for the relevant market and open **Integrations → Clara API → Project credentials**.
2. Click **Create project** and choose a name, a validity period (up to 360 days), and the read/write permissions the integration needs.

| Market | Dashboard |
| - | - |
| Mexico | [app.clara.cc/settings/integrations/clara-api](https://app.clara.cc/settings/integrations/clara-api) |
| Colombia | [colombia.clara.com/settings/integrations/clara-api](https://colombia.clara.com/settings/integrations/clara-api) |
| Brazil | [brasil.clara.com/settings/integrations/clara-api](https://brasil.clara.com/settings/integrations/clara-api) |

Creating the project returns three artifacts, downloadable **once**:

| Artifact | Use |
| - | - |
| Public key | Client certificate for the mTLS layer |
| Private key | Signs the TLS handshake — treat it like a password |
| Client credentials JSON | `client_id`, `client_secret`, and the granted scopes |

If the credentials are lost, they cannot be re-downloaded. Create a new project and retire the old one.

Creating a project does not create an `identity_endpoint`, does not return a grant, and does not register an agent identity.

## Claim

**There is no claim step.** Clara has no `claim_endpoint` and no grant code to redeem: credentials are delivered once, at project creation, directly to the human who created it.

For the same reason, Clara does not accept an `identity_assertion` grant: an ID-JAG (`id-jag`) presented by an agent has nowhere to be redeemed, and no endpoint will validate it.

An agent that receives a `client_id` and `client_secret` is already fully provisioned — there is nothing to claim, exchange for a grant, or poll.

## Exchange

This is the `service_auth` exchange from [Pick a method](#pick-a-method): the client authenticates itself, not an end user. Trade the client credentials for an access token by sending them as HTTP Basic auth, with the client certificate on the request:

```bash theme={null}
curl --request POST "https://public-api.mx.clara.com/oauth/token" \
  --header "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  --cert client.crt \
  --key client.key
```

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}
```

`expires_in` is in seconds. The response above carries no refresh token — to renew, call `/oauth/token` again with the same credentials. Refresh before expiry rather than waiting for a `401`.

The token carries the project's permissions as scopes. It does not carry an agent identity, and it is not scoped down per call: least privilege is enforced by the permissions chosen at project creation.

## Use the access token

Send the `access_token` from the exchange step as a Bearer header, with the certificate, on every request:

```bash theme={null}
curl --request GET "https://public-api.mx.clara.com/api/v3/transactions?page=0&size=10" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

If the account manages several companies, add `X-Tax-Identifier: <tax_id>` to act on behalf of one of them. The same token and certificate work across the group; only the header changes.

## Scopes

Permissions are requested per project and surface as scopes on the token. Common scopes:

| Scope | Grants |
| - | - |
| `read:digital-account` | Read digital-account balance and transactions (Brazil) |
| `read:subscribers` | List webhook subscriptions |
| `write:subscribers` | Create, update, and delete webhook subscriptions |
| `write:accounts-payable/pix` | Create and cancel Pix payments (Brazil) |

The authoritative list for your project is the `scopes` field in the credentials JSON. A request whose token lacks the required scope fails with `403` — retrying will not help; the permission has to be added to the project.

## Errors

| Status | Meaning | What the agent should do |
| - | - | - |
| `400` | Malformed request or missing required field | Fix the request; do not retry as-is |
| `401` | Missing, expired, or invalid Bearer token | Request a new token, retry once |
| `403` | Valid token, insufficient scope or role | Stop; ask the human to grant the permission |
| `404` | Resource does not exist for this company | Verify the identifier; do not retry |
| `511` | mTLS client certificate missing or invalid | Fix the certificate; do not retry |

Clara returns JSON errors, never HTML:

```json theme={null}
{
  "timestamp": "2026-10-26T22:51:37.573+00:00",
  "path": "/api/v3/transactions",
  "status": 511,
  "error": "Network Authentication Required",
  "requestId": "2b37b9af-14425",
  "message": "Mutual TLS (mTLS) required: missing or invalid client certificates in the request."
}
```

**No `WWW-Authenticate` hint:** a `401` or `511` from Clara does not currently carry a `WWW-Authenticate: Bearer resource_metadata="…"` header pointing at machine-readable metadata. When you get one, come back to this page — there is no discovery pointer to follow.

Requests are rate-limited, and every response carries `X-RateLimit-Burst-Capacity`, `X-RateLimit-Replenish-Rate`, `X-RateLimit-Remaining`, and `X-RateLimit-Requested-Tokens`. Back off while `X-RateLimit-Remaining` is low instead of retrying into the limit. See [Error Handling](https://developers.clara.team/error-handling.md) for status codes and retry guidance.

## Revocation

Clara does not publish an endpoint to revoke a token or a project. Consequences to plan for:

* **Tokens** stop working when `expires_in` elapses. There is no revocation endpoint, so do not assume a stolen token dies early.
* **Projects** stop working at the end of the validity selected at creation (maximum 360 days). Renew by creating a new project, switching the integration, and letting the old one expire.
* **Immediate revocation** — for a compromised credential or a project that must be cut off now — goes through Clara integration support:

| Market | Contact |
| - | - |
| Mexico | [integration.support.mx@clara.team](mailto:integration.support.mx@clara.team) |
| Brazil | [integration.support.br@clara.team](mailto:integration.support.br@clara.team) |
| Colombia | [integration.support.co@clara.team](mailto:integration.support.co@clara.team) |

Clara MCP access is revoked the same way: contact Customer Happiness or Solution Engineering, and access is cut off across tools.

## Agent checklist

* [ ] I hold a certificate, a private key, and `client_id` + `client_secret` from a human — not invented
* [ ] I know which market the company belongs to, and I am using that market's host
* [ ] I request a token from `/oauth/token` and renew it before `expires_in` elapses
* [ ] I send the certificate on every request, not just the token call
* [ ] I treat `401` (token) and `511` (certificate) as different failures
* [ ] I keep the requested scopes to the minimum the task needs


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