Authentication

Authentication

v1.13.0

Every request to the public API (/api/v1/...) must be authenticated with an API key. Keys are issued and managed from the dashboard — the public API itself has no key-management endpoints, so a key can never be used to create or revoke other keys.

Creating a Key

1. Go to Organization Settings → API Keys.

2. Click Create Key, give it a name, and select one or more scopes. This form issues a live key — for a sandbox key, see Sandbox instead, which uses a separate provisioning call.

3. Copy the secret shown in the dialog. This is the only time the full key is ever displayed — the dashboard only stores and shows a redacted lastFour afterward.

One-time secret

The full token is returned exactly once, in the response body of the create call. Clienta.ai never stores or logs the secret in recoverable form — only an HMAC digest. If you lose it, revoke the key and create a new one.

Key Format

ck_{environment}_{keyId}.{secret}

• environment is live or sandbox.
• keyId is a 22-character base64url string (128-bit random).
• secret is a 43-character base64url string (256-bit random), separated from keyId by a literal ..

Example: ck_live_8f2N3q...Ab.9xQ1z...pR

Send it as a standard bearer token:

Authorization: Bearer ck_live_8f2N3qkYV2b1jH0mQe4xAb.9xQ1zPr7wLskFn2VmY0aRcTdEjHlBpR

A token that doesn’t match this shape is rejected as 401 Unauthorized before any database lookup — malformed tokens never cost a round trip and are counted separately in our abuse metrics from genuinely invalid/revoked keys.

Scopes

Every key is issued with one or more scopes. A request whose route requires a scope the key doesn’t have is rejected with 403 INSUFFICIENT_SCOPE.

Scope	Grants
read:conversations	Read conversations and messages
read:contacts	Read contacts
read:analytics	Read analytics data
read:channels	Read channel configuration
read:kb	Read knowledge base documents
write:kb	Upload knowledge base documents
read:webhooks	List webhook endpoints and delivery history
write:webhooks	Create, delete, and test webhook endpoints

The API is default-deny: every route under /api/v1 must declare its required scopes explicitly, or the server returns 500 ROUTE_MISCONFIGURED rather than silently allowing the request through.

Tips

Grant a key only the scopes it needs. A read-only integration should never hold a write:* scope.

Environments: live vs. sandbox

A live key operates on your real organization’s data. A sandbox key is routed transparently to a paired sandbox organization with isolated data — see Sandbox for the full model. Sandbox keys always run at the lowest rate-limit tier, regardless of your plan.

Expiration

You can optionally set an expiresAt date when creating a key. An expired key fails verification the same way a revoked one does — 401 Unauthorized — even if it is never explicitly revoked.

Rotation

There is no in-place “rotate” operation — a key’s secret cannot be changed without changing its identity. To rotate a key without downtime:

1. Create a new key with the same scopes and environment as the one you’re rotating.

2. Deploy the new key to your integration and confirm it works.

3. Revoke the old key from Organization Settings → API Keys.

Keep both keys active in parallel during the rollover window — there’s no artificial limit on how many active keys an organization can hold beyond the plan’s active-key cap.

Revocation

Revoking a key is immediate and fails closed: the very next request using that key is rejected with 401 Unauthorized, even if a revocation-check failure occurs on our side (a lookup error never falls back to “allow”).

Revoked keys are never deleted — only marked revokedAt — so delivery/usage history for the key remains auditable.

What we never log

• The plaintext secret — only an HMAC-SHA256 digest (keyed by a versioned server-side pepper) is stored.
• The Authorization header value, in any log line, at any log level.

Internal key-material rotation

The pepper Clienta.ai uses to hash stored key secrets, and the envelope-encryption keys used for webhook signing secrets, are rotated independently of your API keys and require no action on your side — existing keys keep working across a pepper rotation. See Webhook Signature Verification → Secret rotation for how this affects webhook signature verification specifically.