Skip to main content
POST
Create an API key and return its one-time secret

Authorizations

Authorization
string
header
required

Dairo API key, e.g. dairo_test_... or dairo_live_...

Headers

Idempotency-Key
string

Optional idempotency key for safe retries of side-effecting operations.

Maximum string length: 128

Body

application/json
name
string
required
scopes
enum<string>[]
required
Minimum array length: 1

A grantable scope, or one of the bundles messages, letters, phone, admin, which expand server-side before the allowlist check. A key may only request scopes its own key already holds.

Available options:
account:read,
account:write,
admin,
agents:read,
agents:write,
audiences:read,
audiences:write,
buckets:read,
buckets:write,
budgets:read,
budgets:write,
compliance:read,
compliance:write,
contacts:read,
contacts:write,
domains:read,
domains:write,
events:read,
events:write,
inboxes:read,
inboxes:write,
keys:read,
keys:write,
letters,
letters:read,
letters:send,
messages,
messages:read,
messages:send,
phone,
phone:call,
phone:read,
phone:write,
templates:read,
templates:write,
webhooks:read,
webhooks:write
allowedIps
string[] | null

Optional IPv4/IPv6 addresses or CIDR ranges (up to 50) the key may authenticate from. Deny-by-default: a correct secret from an unlisted IP is rejected with 403. Omit or null for any-IP.

environment
enum<string> | null
default:live

Cosmetic LABEL only; picks the secret prefix (dairo_test_…/dairo_live_…). It does NOT create a sandbox: a test key sends real mail, really delivered and really billed. Defaults to live.

Available options:
test,
live,
null
projectId
string | null

Optional organization to bind the key to. Defaults to the caller's active project; you must be a member of the one you name.

inboxIds
string<uuid>[] | null

Optional per-inbox restriction: the inbox ids (inboxes.id, up to 100) this key may send as. Enforced server-side on every send, so it binds a raw POST /v1/messages exactly as much as it binds the CLI. Omit, null, or [] for unrestricted (any inbox). A key that is itself restricted may only grant a subset of its own inboxes; a child that requests none inherits the parent's restriction rather than escaping it.

Response

Success

apiKey
object
required
secret
string
required

One-time API key secret. Store immediately.