Skip to main content
An API key is a long-lived credential your server-side code uses to call the Zeptar API. Unlike session cookies — which are tied to an interactive browser login — an API key travels as a Bearer token in the Authorization header and is valid until you revoke it. Every key belongs to a single workspace. Requests authenticated with a key are scoped to that workspace, subject to the per-key permission scopes you configure at creation time.

​
Lifecycle

Create a key through the dashboard or via POST /v1/api-keys. The plaintext secret — prefixed zsk_ — is returned once in the creation response. Copy it immediately and store it in a secrets manager or environment variable; Zeptar never shows it again. Only a hashed form is retained server-side. Use the key to authenticate /v1 endpoints that declare a permission scope — everything under Agents, Conversations, Knowledge base, Voices, and the workspace read endpoints (see Authenticating requests below). Session-only endpoints reject keys with 403 session_required and must be called from a logged-in browser session: API-key management (/v1/api-keys), the request log (/v1/request-log), /v1/me, workspace invitations, member management, and branch update/merge. Update a key’s name, scopes, or disabled state at any time via PATCH /v1/api-keys/:id. The secret itself does not change. Revoke a key permanently with DELETE /v1/api-keys/:id. Revocation takes effect immediately; any in-flight requests carrying that secret will start receiving 401.

​
Secret format

Secrets always begin with zsk_, followed by a URL-safe random string — for example:
The prefix makes it easy to scan repositories and CI logs for accidental leaks. If you see a zsk_ value somewhere it shouldn’t be, revoke the key immediately and issue a replacement.

​
Authenticating requests

Pass your key in the Authorization header with the Bearer scheme:
In TypeScript / Node.js:

​
Scopes

Every key carries a scopes object that maps the five resource groups to an access level:
  • none — the key is denied access to that resource group entirely.
  • read — the key may call GET endpoints for that group.
  • write — the key may call mutating endpoints (POST, PATCH, DELETE) in addition to GET.
When a request exceeds the key’s scope for that resource, the API returns 403 insufficient_scope.

​
Session-only management

API-key management endpoints — create, list, update, revoke — require an active browser session. An API key cannot be used to create or revoke other API keys. This prevents a compromised key from escalating its own privileges or covering its tracks. Any management call made with a Bearer key returns 403 session_required.

​
Usage limits

The usageLimit field is accepted in both create and update payloads for forward-compatibility, but limit enforcement is not yet active. Setting a value is harmless and will be respected once the enforcement layer ships.