API keys & authentication

Every request to Dairo authenticates with an API key, sent as a bearer token in the Authorization header. One key works across the REST API, the SDKs, the CLI, and the MCP server. The fastest way to confirm a key works is whoami — it returns your userId, your plan, the key’s scopes as apiKey.scopes, and your current usage. It answers for any valid key, whatever its scopes.

curl https://api.dairo.app/v1/whoami \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const me = await dairo.whoami();
console.log(me.userId, me.plan, me.apiKey.scopes);

me = dairo.whoami()
print(me.user_id, me.plan, me.api_key.scopes)

dairo whoami

Create a key

API keys are long-lived credentials for server-side code, CI, agents, and the CLI. Create one from the dashboard, or over the API with a key that carries keys:write.

const { apiKey, secret } = await dairo.apiKeys.create({
  name: "production-worker",
  scopes: ["messages:send", "messages:read"],
});
console.log(apiKey.id);   // the key id   (safe to store and display)
console.log(secret);      // dairo_live_… (shown once — store it now)

created = dairo.api_keys.create(
    name="production-worker",
    scopes=["messages:send", "messages:read"],
)
print(created.api_key.id)
print(created.secret)  # dairo_live_… (shown once)

dairo api-key create --name production-worker --scope messages:send --scope messages:read
# Prints the one-time secret. Store it now; it is never shown again.

curl -X POST https://api.dairo.app/v1/api-keys \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-worker","scopes":["messages:send","messages:read"]}'

The secret (dairo_live_…) is shown once, at creation, and never again. Capture it immediately. If you lose it, revoke the key and create a new one.

List and revoke keys whenever you need to:

dairo api-key list
dairo api-key revoke key_123

Lock a key to trusted IPs

Pass allowedIps at creation — up to 50 IPv4/IPv6 addresses or CIDR ranges — to bind a key to specific source addresses. Enforcement is deny-by-default: the correct secret from an unlisted IP is rejected with a 403. See Audit logs for the full setup and lockout recovery.

Scope every key to what it needs

Each key carries a set of scopes that decide what it can do. Every resource owns its own read/write pair, and a read is never gated behind a write scope. The ones you’ll reach for first:

Scope	Grants
`messages:read`	Read messages, threads, attachments, and delivery events.
`messages:send`	Send, schedule, and cancel outbound messages.
`inboxes:read` / `inboxes:write`	Read / create, update, and delete inboxes.
`contacts:read` / `contacts:write`	Read / create, update, and delete contacts and their handles.
`domains:read` / `domains:write`	Read / add, verify, update, and delete domains.
`webhooks:read` / `webhooks:write`	Read / create, update, and delete webhooks.
`templates:read` / `templates:write`	Read / author and version templates.
`audiences:read` / `audiences:write`	Read / create, add members to, and broadcast to audiences.
`keys:read` / `keys:write`	Read / create, update, and revoke API keys.

Bundles save you the enumeration: request messages and it expands to messages:read + messages:send; letters and phone bundle the same way, and admin expands to every scope. See Permissions & scopes for the full list and the exact scope each endpoint needs. Grant the narrowest set a workload needs. A key can only mint child keys whose scopes are a subset of its own — so a messages:send-only key can never create one with broader access.

Use your key from any surface

SDKs
CLI
MCP server

The Python SDK reads DAIRO_API_KEY from the environment, or takes the key explicitly:

from dairo import Dairo
dairo = Dairo()                        # reads DAIRO_API_KEY
dairo = Dairo(api_key="dairo_live_…")  # explicit

The JavaScript SDK never reads the environment on its own — so browser and edge runtimes stay predictable — and the other SDKs also take the key explicitly:

const dairo = new Dairo({ apiKey: process.env.DAIRO_API_KEY! });

The CLI reads DAIRO_API_KEY first, then the local config. To store a key in the config, pipe it to dairo auth token set — the token is read from stdin only, never a positional argument, so your secret stays out of shell history and process listings:

printf '%s' "$DAIRO_API_KEY" | dairo auth token set

In CI, prefer the environment variable.

The hosted MCP endpoint is https://mcp.dairo.app/mcp. It authenticates with the same bearer key and advertises typed tool schemas, so an agent discovers required fields before it calls:

claude mcp add --transport http dairo https://mcp.dairo.app/mcp

See the MCP server guide for full setup.

Handle a failed request

Auth failures — and every other error — come back in one shape: { "error": { "type", "code", "message", "param" } }. Branch on the stable machine code, never on the prose message. See Errors for the full code list.

Verify webhook signatures

Webhook deliveries are signed so you can confirm they came from Dairo. Verify the signature against the raw request body — see Verify the signature.

Keep your secrets safe

Store keys in a secret manager — Vault, Doppler, AWS Secrets Manager, or your host’s environment config. Never commit a key or ship one in a client-side bundle.
Keep keys out of URLs and logs. Keys belong in the Authorization header, never a query string. Scrub them from logs, screenshots, and error reports.
Rotate after tests and on suspicion. Revoke keys used for temporary tests, and rotate immediately if a key may have been exposed.
Use one key per workload. A separate key per service makes revocation surgical and usage traceable.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

API keys & authentication

Create a key

Lock a key to trusted IPs

Scope every key to what it needs

Use your key from any surface

Handle a failed request

Verify webhook signatures

Keep your secrets safe

​Create a key

​Lock a key to trusted IPs

​Scope every key to what it needs

​Use your key from any surface

​Handle a failed request

​Verify webhook signatures

​Keep your secrets safe

Create a key

Lock a key to trusted IPs

Scope every key to what it needs

Use your key from any surface

Handle a failed request

Verify webhook signatures

Keep your secrets safe