Skip to main content

​
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: Click Create project and fill in the form: Once created, download your credentials. You will receive three items:
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.
To request API access for the first time: Contact your Customer Success Manager or Clara’s Customer Happiness team:

​
Step 2: Get an access token

Use your client certificate, private key, client_id, and client_secret to request a token:
The response contains your Bearer token:
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.
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.
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:

​
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:
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 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.

​
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: Use this dashboard to detect unusual traffic spikes, spot failing endpoints before they affect your integration, and plan capacity ahead of billing resets.