Skip to main content
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: Every market has its own host and its own token endpoint: 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. 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.
Creating the project returns three artifacts, downloadable once: 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: 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:
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:
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: 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

Clara returns JSON errors, never HTML:
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 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:
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