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

# API Keys

> Generate and manage swb_-prefixed API keys for programmatic access to the Switchbord public REST API.

API keys are how external systems and scripts authenticate against Switchbord's public REST API without an interactive login session. Keys are workspace-scoped — a key can only see and operate on the workspace it was created in — and are shown in full exactly once, at creation time.

## Where to manage keys

Go to **Settings → Integrations → API Keys**. Creating, revoking, and deleting keys requires the `owner` or `admin` role for the workspace; any workspace member can view the list of existing keys (by name and prefix only — never the full secret).

## Creating a key

1. Click **Create key**.
2. Give it a descriptive name (e.g. "Production integration", "Zapier sync").
3. Choose a scope (see below).
4. Optionally set an expiry — **Never**, 30 days, 90 days, or 1 year.
5. Click **Create key**. The full key is displayed once in a dialog — copy it immediately. Switchbord stores only a SHA-256 hash and an 8-character prefix for display; the raw secret cannot be recovered afterward.

<Warning>
  If you lose a key, there's no way to retrieve it again — revoke it and create a new one. Never paste a live key into client-side code, a committed file, or a chat message.
</Warning>

## Key format

Generated keys are prefixed `swb_` (some legacy provisioning tooling and internal scripts still mint `sk_live_`-prefixed keys for bootstrap purposes — both formats validate the same way). The prefix makes keys easy to spot in logs and diffs, and lets automated secret-scanning catch an accidentally committed key quickly.

## Scopes

Every key is created with exactly one scope, which bounds what it can do regardless of which endpoint it calls:

| Scope        | Grants                                                                                    |
| ------------ | ----------------------------------------------------------------------------------------- |
| `data_read`  | Read contacts, conversations, and templates.                                              |
| `data_write` | Create and update records — sending messages, scheduling campaigns, writing contact data. |
| `management` | Full API key and settings access, in addition to data operations.                         |
| `webhook`    | Send webhook-triggered events.                                                            |

Choose the narrowest scope that does the job — a script that only needs to read contacts shouldn't hold a `management` key.

## Authenticating requests

Pass the key as a Bearer token:

```http theme={null}
Authorization: Bearer swb_...
```

Switchbord resolves the calling workspace directly from the key — never send a workspace ID in the request body and expect it to be trusted. On each request, the key hash is looked up, checked against its scope and expiration, and `last_used_at` is updated.

## Revoking and deleting

* **Revoke** immediately invalidates a key for authentication while keeping its record (and usage history) visible in the list, marked as revoked.
* **Delete** removes the key record entirely.

Every create, revoke, and delete action is written to the workspace audit log, so you can always answer "who issued this key and when."

## Expiry

Keys can be set to never expire, or to expire automatically after 30 days, 90 days, or 1 year. An expired key fails authentication the same way a revoked one does — requests return a 403 rather than silently succeeding.

## See also

* [API Reference — Introduction](/api-reference/introduction) — the public REST API surface, base URL, and core v1 endpoints.
* [Template API endpoints](/api-reference/template-endpoints) — an example of an authenticated, scope-checked route.
* [Security — Secrets & Encryption](/security/secrets-and-encryption) — how keys and other secrets are hashed and stored at rest.