Authentication

Every Wordcab request uses a Bearer API key. Create them in the dashboard or by API, scope them narrowly, rotate them safely.

Every request needs a Bearer token. Keys are created in the dashboard or via the API keys endpoint. The SDKs pick the token up from WORDCAB_API_KEY automatically; you can also pass it explicitly.

Creating a key

Sign in at wordcab.com.
Open Settings → API Keys.
Click Create API key, give it a name and optional scopes, and copy the token.

Keys are shown once

The full secret is only shown at creation time. Store it in your secret manager immediately, you can always revoke and rotate.

Using a key

from wordcab import Wordcab

# Picks up WORDCAB_API_KEY from the environment
client = Wordcab()

# Or pass it explicitly
client = Wordcab(api_key="wc_live_xxxxxxxxxxxxxxxx")

import { Wordcab } from "@wordcab/sdk";

const client = new Wordcab();                    // env var
const client2 = new Wordcab({ apiKey: "wc_..." }); // explicit

curl https://api.wordcab.com/api/v1/agents \\
  -H "Authorization: Bearer wc_live_xxxxxxxxxxxxxxxx"

Key prefixes

Every key has a visible prefix so you can tell environments apart in logs and incident reports.

Prefix	Environment	Notes
`wc_live_`	Production	Cloud API production. Billable traffic.
`wc_test_`	Test	Sandbox. Not billable. Some fine-tuning endpoints are stubbed.
`wc_sh_`	Self-hosted	Issued by a self-hosted control plane. The secret never leaves your cluster.

Scopes

Scopes bound a key's capabilities. Unscoped keys (*) are convenient during development but should be replaced with narrow keys in production.

Scope	Description
`*`	Full access to everything the owning user can reach.
`transcripts:read`	List and retrieve transcripts.
`transcripts:write`	Create transcription jobs.
`speech:write`	Generate speech.
`agents:read` / `agents:write`	View / create voice agents and configuration.
`calls:read` / `calls:write`	View calls / place outbound calls and end active calls.
`gym:read` / `gym:write`	Read or run test suites and experiments.
`deploy:read` / `deploy:write`	Read or manage self-hosted deployment objects.
`webhooks:write`	Register and manage webhook endpoints.

Creating a scoped key via API

bash

curl -X POST https://api.wordcab.com/api/v1/api-keys \\
  -H "Authorization: Bearer $WORDCAB_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "transcription-worker",
    "scopes": ["transcripts:read", "transcripts:write"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Rotating keys

Create a replacement key before revoking the old one, verify traffic is flowing on the new key in your logs, then revoke.

bash

# 1. Create the replacement
wordcab keys create --name "transcription-worker-2026q2" --scope transcripts:write

# 2. Roll your app's secret, verify traffic under the new key id

# 3. Revoke the old one
wordcab keys revoke key_01H...

Self-hosted deployments

On self-hosted installations, keys are issued by your control plane, not api.wordcab.com. The secret material never leaves the cluster and can be rotated without a support ticket.

Issue keys via the CLI: wordcab --env on-prem keys create
Integrate with your IdP: SAML and OIDC for users, SCIM for groups, and scoped service tokens for workloads.
Stream the audit log (key created / used / revoked) to your SIEM over syslog or webhook.

Short-lived tokens

For workload-to-workload traffic inside a cluster, prefer short-lived tokens minted from your service mesh or IdP over long-lived API keys. The control plane accepts any OIDC-signed JWT you configure.

← Previous

Quickstart

Errors