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
- 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.
- 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:
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) |
| 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 |
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.
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.
Step 2: Get an access token
Use your client certificate, private key, client_id, and client_secret to request a token:
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
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
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.
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.
- 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:
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:
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"
X-Tax-Identifier value changes per request.
Postman setup
For teams who prefer Postman over raw curl:
- Download the latest API spec from api-docs-v3.json and import it into Postman.
- In Settings → Certificates, upload your CA certificate and client certificate (
.crt + .key) for host public-api.mx.clara.com on port 443.
- 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.
- Generate the token and start making requests.
If you need further assistance, refer to the Clara help center.
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:
| 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 |
