---
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`](#api-keys-create) | Create API key |
| [`api-keys delete`](#api-keys-delete) | Delete API key |
| [`api-keys get`](#api-keys-get)       | Get API key    |
| [`api-keys list`](#api-keys-list)     | List API keys  |
| [`api-keys update`](#api-keys-update) | Update API key |

Every command also takes the [global flags](https://machinemail.dev/docs/cli/commands#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.

```bash
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` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
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`](https://machinemail.dev/docs/reference/api/api-keys#create-api-key)
- [`POST /v0/inboxes/{inbox_id}/api-keys`](https://machinemail.dev/docs/reference/api/api-keys#create-api-key-in-inbox) with `--inbox`
- [`POST /v0/pods/{pod_id}/api-keys`](https://machinemail.dev/docs/reference/api/api-keys#create-api-key-in-pod) 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.

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

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

#### API

- [`DELETE /v0/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#delete-api-key)
- [`DELETE /v0/inboxes/{inbox_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#delete-api-key-in-inbox) with `--inbox`
- [`DELETE /v0/pods/{pod_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#delete-api-key-in-pod) with `--pod`

## api-keys get

Get API key.

Also returns revoked keys (with revoked\_at).

Requires the api\_key\_read permission.

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

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

#### API

- [`GET /v0/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#get-api-key)
- [`GET /v0/inboxes/{inbox_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#get-api-key-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#get-api-key-in-pod) 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.

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

```bash
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`](https://machinemail.dev/docs/reference/api/api-keys#list-api-keys)
- [`GET /v0/inboxes/{inbox_id}/api-keys`](https://machinemail.dev/docs/reference/api/api-keys#list-api-keys-in-inbox) with `--inbox`
- [`GET /v0/pods/{pod_id}/api-keys`](https://machinemail.dev/docs/reference/api/api-keys#list-api-keys-in-pod) 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.

```bash
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` |  | Request body as JSON, @file or - for stdin; field flags override its keys. |

#### Examples

```bash
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}`](https://machinemail.dev/docs/reference/api/api-keys#update-api-key)
- [`PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#update-api-key-in-inbox) with `--inbox`
- [`PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}`](https://machinemail.dev/docs/reference/api/api-keys#update-api-key-in-pod) with `--pod`