deeprelayDocs
CH·02CLI reference

deeprelay api-keys create

Create an API key (the key is shown once)

Create an API key (the key is shown once)

Synopsis

Creates an API key and prints it once. Copy it straight away: no command, page or API call can show it again. If you lose it, revoke the key and create another.

Required:

  • --name — a label you will recognise in the request log and the key list
  • --scopes — standard (inference and everyday resources, no key management), read_only, full_access, or a JSON scope object such as '{"serverless":"write"}'

Optional limits (each defaults to no limit, or to your own key's limit when that is tighter):

  • --budget — monthly budget, e.g. 5 or 12.50; must be more than $0
  • --allow-model — repeat once per model the key may call
  • --rps , --burst — rate limit
  • --expires — RFC3339 or a date (2027-01-01, midnight UTC); must be in the future
  • --manage-keys — let the key create, change and revoke keys. Off by default. Never use it for a key that a tool or editor config will hold.
  • --fallback-model — a backup model (repeatable, in priority order, at most 3). See Backup models below. Fallback is off unless you pass it; --no-fallback states that explicitly and cannot be combined with --fallback-model.

Backup models

A key can carry an ordered list of up to 3 backup models. When every provider for the requested model fails before the first byte of the response — an error, a timeout, or a first-token stall — the request moves to the next backup in the list, and so on. Once a response has started streaming it is never switched to another model.

  • Every backup must be a chat model in the catalog and, when the key has an allowlist, inside it. Order is kept exactly as you type it; duplicates are dropped by the server.
  • A plan-covered request stays plan-covered: a backup your plan does not cover is marked (wallet only) and is used only for wallet-billed requests. A backup that has left the catalog is marked (unavailable) and skipped.
  • A backup can cost more than the model you usually call. api-keys get shows each backup's current price and marks the ones above the key's most-used model.
  • One request can override the list with the X-Deeprelay-Fallback-Models header; the override can never reach a model the key may not call.
  • Backup lists are not applied to Liquid: a Liquid job is always served by exactly the model it was awarded.
  • The response, the request log and billing name the model that actually served; deeprelay requests list --fallback shows the requests that used a backup.

Everything you ask for must fit inside the key making the request. When it does not, the command explains and exits 1:

  • this key cannot manage keys; log in with deeprelay login or use a full_access key — the calling key lacks keys:manage
  • requested scopes exceed your key's scopes — the new key would get access the calling key does not have
  • a limit above your own (budget, rate limit, a later expiry, a model outside your allowlist) is refused with the server's explanation

Bad flag values are refused before anything is sent. With -o json the response prints as-is, the key in its key field.

Examples

# A key for a CI job: $5 a month, one model, expires at year end
deeprelay api-keys create --name ci-bot --scopes standard --budget 5 \
  --allow-model deeprelay/deepseek-v4.1-flash --expires 2026-12-31

# An agent key that falls back to two backups, in this order
deeprelay api-keys create --name agent --scopes standard \
  --fallback-model deeprelay/glm-5.3 --fallback-model deeprelay/kimi-k3

# A read-only key for a dashboard
deeprelay api-keys create --name metrics --scopes read_only

# Capture the key in a script
KEY=$(deeprelay api-keys create --name batch --scopes standard -o json | jq -r .key)

deeprelay api-keys create [flags]

Options

      --allow-model stringArray      Allow only this model id (repeatable; default: all models)
      --budget string                Monthly budget in dollars, e.g. 5 or 12.50 (default: no budget)
      --burst int                    Burst size (default: platform default, or your key's lower limit)
      --expires string               Expiry, RFC3339 or YYYY-MM-DD in UTC (default: never)
      --fallback-model stringArray   Backup model tried when every provider for the requested model fails before the first byte (repeatable, in order; max 3)
  -h, --help                         help for create
      --manage-keys                  Let this key create, change and revoke keys. Never give this to a key used by a tool
      --name string                  Key name (required)
      --no-fallback                  Leave model fallback off for this key (the default)
      --rps int                      Requests per second (default: platform default, or your key's lower limit)
      --scopes string                standard | read_only | full_access, or a JSON scope object (required)

Options inherited from parent commands

      --api-base string   API base URL (override with DEEPRELAY_API_BASE env) (default "https://api.deeprelay.ai/v1")
      --debug             Enable debug logging to stderr
      --no-preflight      Skip the plan/credit check before inference requests (override with DEEPRELAY_NO_PREFLIGHT env)
  -o, --output string     Output format: table|json (default table on TTY, json otherwise) (default "table")

SEE ALSO

  • deeprelay api-keys - Create and manage API keys with budgets, model allowlists and rate limits

← The deeprelay CLI