api-keys · MachineMail Docs

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.

Requires the api_key_create permission.

shell

machinemail api-keys create [flags]

Flags

--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.

DefaultAPI key

--permissions <json>JSON | null

Permissions of the new key. Omitted or null: full access for the key scope (inbound_raw excepted). null clears the value.

--expires-at <time>string | null

When the key stops working (a past time creates a key that is already expired). Omitted, the key does not expire. It cannot be changed later. null clears the value.

-d, --data <json|@file|->string

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

machinemail api-keys create
machinemail api-keys create --inbox agent@machinemail.dev
machinemail api-keys create --data @body.json
machinemail api-keys create --permissions null   # clears permissions

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.

shell

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

Arguments

<api-key-id>stringRequired

ID of the API key.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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.

shell

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

Arguments

<api-key-id>stringRequired

ID of the API key.

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

Examples

shell

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.

shell

machinemail api-keys list [flags]

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

--typebearer | 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.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

Oldest first.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

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

Arguments

<api-key-id>stringRequired

ID of the API key.

Flags

--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

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

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