api keys.md

title: "api-keys" description: "Organization, pod and inbox scoped keys. The machinemail api-keys commands: arguments, flags, examples and the API routes they call." canonical: "https://machinemail.dev/docs/cli/commands/api-keys"

api-keys

Organization, pod and inbox scoped keys. The machinemail api-keys commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/api-keys

Organization, pod and inbox scoped keys. Also spelled api-key, keys.

Command Summary
api-keys create Create API key
api-keys delete Delete API key
api-keys get Get API key
api-keys list List API keys
api-keys update Update API key

Every command also takes the global flags.

api-keys create

Create API key.

The route sets the scope of the new key: POST /v0/api-keys makes an organization key, POST /v0/pods/{pod_id}/api-keys a pod key, POST /v0/inboxes/{inbox_id}/api-keys an inbox key.

Only organization-scoped credentials (and dashboard sessions) can create keys, and only with permissions they have themselves (403). api_key is returned once.

--expires-at makes a key that stops working at that time (401 after it). A key created with an expiring API key never outlives it.

Requires the api_key_create permission.

machinemail api-keys create [flags]

Flags

Field Type Description
--inbox <inbox-id> string Create it in this inbox.
--pod <pod-id> string Create it in this pod.
--name <value> string Name of the key. Default API key. Default: API key.
--permissions <json> JSON | null Permissions of the new key. Omitted or null: full access for the key scope (inbound_raw excepted).
--expires-at <time> string | null When the key stops working, as an RFC 3339 timestamp at least 5 minutes from now (400 otherwise). A date alone or a time without a zone is read as UTC. Omit it or send null for no expiry (a key created with an expiring API key gets that key’s expiry instead). A key created with another API key cannot outlive it: a later time is a 403. An inherited expiry can be under 5 minutes away. It cannot be changed later; create a new key instead.
--expires-in <duration> string Key stops working after this long: 90m, 12h, 30d, 2w or 1y (at least 5 minutes). Sets expires_at; not with --expires-at.
`-d, --data <json @file ->` string

Examples

machinemail api-keys create --name ci --expires-in 30d
machinemail api-keys create --name agent --inbox agent@machinemail.dev --expires-at 2027-01-01T00:00:00Z
machinemail api-keys create --inbox agent@machinemail.dev
machinemail api-keys create --data @body.json

API

api-keys delete

Delete API key.

Also: machinemail api-keys rm.

Revokes the key: it stops working immediately. The record is kept (with revoked_at) and no longer listed.

Requires the api_key_delete permission.

machinemail api-keys delete <api-key-id> [flags]

Arguments

Field Type Description
<api-key-id> string required ID of the API key.

Flags

Field Type Description
--inbox <inbox-id> string Use this inbox's scoped route.
--pod <pod-id> string Use this pod's scoped route.

Examples

machinemail api-keys delete key_01m4g463jy0002nz2drf5r5bvx
machinemail api-keys delete key_01m4g463jy0002nz2drf5r5bvx --inbox agent@machinemail.dev

API

api-keys get

Get API key.

Also returns revoked keys (with revoked_at).

Requires the api_key_read permission.

machinemail api-keys get <api-key-id> [flags]

Arguments

Field Type Description
<api-key-id> string required ID of the API key.

Flags

Field Type Description
--inbox <inbox-id> string Only this inbox.
--pod <pod-id> string Only this pod.

Examples

machinemail api-keys get key_01m4g463jy0002nz2drf5r5bvx
machinemail api-keys get key_01m4g463jy0002nz2drf5r5bvx --inbox agent@machinemail.dev

API

api-keys list

List API keys.

Also: machinemail api-keys ls.

Keys that are not revoked. Under /v0/pods/{pod_id} or /v0/inboxes/{inbox_id}, only the keys scoped to that pod or inbox; a pod or inbox credential sees only keys in its own scope.

Requires the api_key_read permission.

machinemail api-keys list [flags]

Flags

Field Type Description
--inbox <inbox-id> string Only this inbox.
--pod <pod-id> string Only this pod.
--type bearer | public_key Only this credential family. Every key is bearer, so public_key returns an empty list.
--limit <n> integer Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: 50.
--page-token <value> string next_page_token from the previous page.
--ascending boolean Oldest first.
--all boolean Follow next_page_token and return every page.

Examples

machinemail api-keys list
machinemail api-keys list --inbox agent@machinemail.dev
machinemail api-keys list --all --json | jq '.api_keys | length'

API

api-keys update

Update API key.

Rename a key or replace its permissions. Only organization-scoped credentials (and dashboard sessions) can update keys, and cannot grant permissions they lack (403).

Requires the api_key_update permission.

machinemail api-keys update <api-key-id> [flags]

Arguments

Field Type Description
<api-key-id> string required ID of the API key.

Flags

Field Type Description
--inbox <inbox-id> string Use this inbox's scoped route.
--pod <pod-id> string Use this pod's scoped route.
--name <value> string New name. A blank name is ignored.
--permissions <json> JSON New permissions; replaces the permission object in full.
`-d, --data <json @file ->` string

Examples

machinemail api-keys update key_01m4g463jy0002nz2drf5r5bvx
machinemail api-keys update key_01m4g463jy0002nz2drf5r5bvx --inbox agent@machinemail.dev
machinemail api-keys update key_01m4g463jy0002nz2drf5r5bvx --data @body.json

API