API keys

An API key authenticates every /v1 request. A key resolves to your account's tenancy — the render is billed and brand-themed against that account's workspace.

Create a key

Mint keys in the app at Settings → API keys while signed in (key management is session-authenticated, not done with an API key).

The plaintext key is shown once, at creation — it is never retrievable again. Copy it immediately and store it in a secret manager or your platform's environment-variable store. The key list afterwards shows only the id, prefix, label, created date, and last-used time — never the secret.

Scope & capabilities

A key inherits your account's subscription capabilities:

  • Using a key for renders / reads requires an active or trialing subscription (canUseApiKey).
  • Creating, editing, or deleting owned templates (wtpl_…) additionally requires the canEditVariables capability — a key without it gets 403 forbidden on those writes, while reads and renders still work.

Store it safely

  • Keep keys server-side; never ship one in client-side code, a mobile app bundle, or a public repo.
  • Use a separate key per environment (staging vs production) so you can revoke one without disrupting the other.

Rotate without downtime

Multiple live keys are supported, so rotation is zero-downtime:

  1. Mint a new key in Settings → API keys.
  2. Switch your integration to the new key.
  3. Revoke the old key once traffic has moved.

Revoking takes effect immediately — a revoked key returns 401 unauthorized. If a key leaks, revoke it right away and mint a replacement.

See Authentication for how to send the key on each request.