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

# Authentication

> mTLS + OAuth 2.0 Bearer token — both required for every request.

## Overview

Clara's API uses two-layer authentication: **mTLS** (mutual TLS) for the connection and **OAuth 2.0 Bearer token** for each request. Both must be present — a valid token without a client certificate will be rejected, and vice versa.

***

## How it works

1. **Certificate layer (mTLS):** Your client certificate authenticates the connection at the TLS level. Without a valid certificate, the handshake fails before any HTTP request is made.
2. **Token layer (OAuth 2.0):** Each HTTP request must include an `Authorization: Bearer <token>` header. Tokens are short-lived JWTs obtained from the `/oauth/token` endpoint using your `client_id` and `client_secret`.

Together, these two layers ensure that only authorized clients with valid credentials can interact with the API.

***

## Step 1: Create an API project

API credentials are managed directly from the Clara dashboard — no need to contact support for each new project.

Navigate to **Integrations → Clara API → Project credentials** for your country:

| Country  | Dashboard URL                                                                                                    |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| 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)     |

Click **Create project** and fill in the form:

| Field                    | Description                                                                                          |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Project**              | A name to identify this credential set (e.g., "ERP Integration – Prod")                              |
| **Validity**             | How long the credentials will remain active — up to 360 days                                         |
| **Permissions to write** | Which write operations this project can perform (e.g., Write cards, Write users, Write transactions) |
| **Permissions to read**  | Which read operations this project can perform (e.g., Read cards, Read transactions)                 |

Once created, download your credentials. You will receive three items:

| File                          | Purpose                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| **Public key**                | Client certificate for encryption/verification                                               |
| **Private key**               | Secret key for decryption/signing                                                            |
| **Client Credentials (JSON)** | JSON with Client ID, Client Secret, and scopes — use for Postman or automated token requests |

<Warning>
  **One-time download only** — certificates won't be accessible once this window closes. Store the private key securely and treat it like a password; it cannot be retrieved again.
</Warning>

<Note>
  Projects expire after the validity period you select (max 360 days). Clara will alert you when projects are approaching expiration. Renew before expiry to avoid service interruption — create the new project first, update your integration, then let the old one expire.
</Note>

**To request API access for the first time:** Contact your Customer Success Manager or Clara's Customer Happiness team:

* Mexico: [contacto@clara.com](mailto:contacto@clara.com)
* Colombia: [contacto.co@clara.com](mailto:contacto.co@clara.com)
* Brazil: [contato@clara.com](mailto:contato@clara.team)

***

## Step 2: Get an access token

Use your client certificate, private key, `client_id`, and `client_secret` to request a token:

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

The response contains your Bearer token:

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

The `expires_in` value is in seconds. Store it and refresh the token proactively before it expires — do not wait for a `401` to trigger a refresh.

<Note>
  Token endpoint URLs are country-specific. Use `public-api.mx.clara.com/oauth/token` for Mexico, `public-api.br.clara.com/oauth/token` for Brazil, and `public-api.co.clara.com/oauth/token` for Colombia.
</Note>

**Best practices for production integrations:**

* Cache the token for its full lifetime to avoid unnecessary token requests.
* If you receive a `401` on a previously working request, refresh the token and retry once before raising an error.

***

## Step 3: Make an authenticated request

Include your client certificate, private key, and Bearer token in every API request:

```bash theme={null}
curl -v https://public-api.mx.clara.com/api/v3/transactions \
  --cert /path/to/client-cert.pem \
  --key /path/to/client-key.pem \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..." \
  -H "Content-Type: application/json"
```

***

## Multi-entity accounts (X-Tax-Identifier)

If your account manages a group of companies (such as a holding), your token can assume the role of a specific entity without requiring separate credentials. Include the `X-Tax-Identifier` header with the target company's Tax ID:

```bash theme={null}
curl -v https://public-api.mx.clara.com/api/v3/transactions \
  --cert /path/to/client-cert.pem \
  --key /path/to/client-key.pem \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..." \
  -H "X-Tax-Identifier: ACME8001011H0" \
  -H "Content-Type: application/json"
```

The same connection, certificates, and credentials work across all entities in the group — only the `X-Tax-Identifier` value changes per request.

***

## Postman setup

For teams who prefer Postman over raw curl:

1. Download the latest API spec from [api-docs-v3.json](https://docs-public-api.clara.com/api-docs-v3.json) and import it into Postman.
2. In **Settings → Certificates**, upload your CA certificate and client certificate (`.crt` + `.key`) for host `public-api.mx.clara.com` on port `443`.
3. On any endpoint, set Authorization type to **OAuth 2.0**, point the Access Token URL to `public-api.mx.clara.com/oauth/token`, and enter your `client_id` and `client_secret`.
4. Generate the token and start making requests.

If you need further assistance, refer to the [Clara help center](https://ayuda.clara.com.mx/hc/es-mx/articles/17827687040787-Clara-API).

***

## Monitor API usage

The **Insights** section gives you a live view of your integration's performance: requests consumed vs. remaining, success rate, and a breakdown by endpoint.

Navigate to **Integrations → Clara API → API Insights** for your country:

| Country  | Insights URL                                                                                                                       |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Mexico   | [app.clara.cc/settings/integrations/clara-api/insights](https://app.clara.cc/settings/integrations/clara-api/insights)             |
| Colombia | [colombia.clara.com/settings/integrations/clara-api/insights](https://colombia.clara.com/settings/integrations/clara-api/insights) |
| Brazil   | [brasil.clara.com/settings/integrations/clara-api/insights](https://brasil.clara.com/settings/integrations/clara-api/insights)     |

| Metric                            | What it tells you                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Remaining requests**            | How many API calls remain in the current billing period                                                 |
| **Total requests**                | Requests made this month, with trend vs. prior month                                                    |
| **Success rate**                  | Percentage of requests that returned a 2xx response                                                     |
| **Service performance breakdown** | Per-service breakdown (e.g., `TransactionsRead`, `OauthTokenWrite`) with request count and success rate |

Use this dashboard to detect unusual traffic spikes, spot failing endpoints before they affect your integration, and plan capacity ahead of billing resets.