Skip to main content
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.
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.

​
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: 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:
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