> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeptar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys overview

> API keys let server-side clients authenticate against the Zeptar API without a browser session.

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

```mermaid theme={null}
flowchart LR
  Create([POST /v1/api-keys]) --> Store[(Store the secret once)]
  Store --> Use([Authenticate requests])
  Use --> Update([PATCH /v1/api-keys/:id])
  Use --> Revoke([DELETE /v1/api-keys/:id])
```

**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](#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:

```
zsk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
```

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:

```bash theme={null}
curl https://api.zeptar.com/v1/agents \
  -H "Authorization: Bearer zsk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
```

In TypeScript / Node.js:

```ts theme={null}
const res = await fetch('https://api.zeptar.com/v1/agents', {
  headers: {
    Authorization: `Bearer ${process.env.ZEPTAR_API_KEY}`,
  },
});
```

## Scopes

Every key carries a **scopes** object that maps the five resource groups to an access level:

| Resource group   | Levels available          | What it gates                                     |
| ---------------- | ------------------------- | ------------------------------------------------- |
| `agents`         | `none` / `read` / `write` | Reading agent config and triggering conversations |
| `conversations`  | `none` / `read` / `write` | Listing and reading past conversation records     |
| `knowledge_base` | `none` / `read` / `write` | Managing knowledge documents attached to agents   |
| `voices`         | `none` / `read` / `write` | Listing available TTS voices                      |
| `workspace`      | `none` / `read` / `write` | Reading workspace members and settings            |

* **`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.

## Related

* [Authentication](/api-reference/authentication) — session cookies, public endpoints, and error shapes.
* [POST /v1/api-keys](/api-reference/api-keys) — create a key.
* [GET /v1/api-keys](/api-reference/api-keys) — list keys for the active workspace.
* [PATCH /v1/api-keys/{id}](/api-reference/api-keys) — update name, scopes, or disabled state.
* [DELETE /v1/api-keys/{id}](/api-reference/api-keys) — revoke a key permanently.