api-keys · MachineMail Docs

api-keys create

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	Description
`--inbox <inbox-id>`	Create it in this inbox.
`--pod <pod-id>`	Create it in this pod.
`--name <value>`	Name of the key. Default API key.
`--permissions <json>`	Permissions of the new key. Omitted or null: full access for the key scope (inbound_raw excepted).
`--expires-at <time>`	When the key stops working, as an RFC 3339 timestamp at least 5 minutes from now (400 otherwise).
`--expires-in <duration>`	Key stops working after this long: 90m, 12h, 30d, 2w or 1y (at least 5 minutes).
`-d, --data <json	@file

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

POST /v0/api-keys
POST /v0/inboxes/{inbox_id}/api-keys with --inbox
POST /v0/pods/{pod_id}/api-keys with --pod

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	Description
`<api-key-id>`	Required - ID of the API key.

Flags

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

Examples

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

API

DELETE /v0/api-keys/{api_key_id}
DELETE /v0/inboxes/{inbox_id}/api-keys/{api_key_id} with --inbox
DELETE /v0/pods/{pod_id}/api-keys/{api_key_id} with --pod

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	Description
`<api-key-id>`	Required - ID of the API key.

Flags

Field	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.

Examples

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

API

GET /v0/api-keys/{api_key_id}
GET /v0/inboxes/{inbox_id}/api-keys/{api_key_id} with --inbox
GET /v0/pods/{pod_id}/api-keys/{api_key_id} with --pod

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	Description
`--inbox <inbox-id>`	Only this inbox.
`--pod <pod-id>`	Only this pod.
`--type`	bearer
`--limit <n>`	Maximum number of items to return. Default 50, maximum 500; larger values are capped.
`--page-token <value>`	next_page_token from the previous page.
`--ascending`	Oldest first.
`--all`	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

GET /v0/api-keys
GET /v0/inboxes/{inbox_id}/api-keys with --inbox
GET /v0/pods/{pod_id}/api-keys with --pod

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	Description
`<api-key-id>`	Required - ID of the API key.

Flags

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

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

PATCH /v0/api-keys/{api_key_id}
PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id} with --inbox
PATCH /v0/pods/{pod_id}/api-keys/{api_key_id} with --pod