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