# api-keys create

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

| Command                                | Summary                |
|----------------------------------------|------------------------|
| [`api-keys create`](/content/docs/cli/commands/api-keys#api-keys-create/index.html) | Create API key         |
| [`api-keys delete`](/content/docs/cli/commands/api-keys#api-keys-delete/index.html) | Delete API key         |
| [`api-keys get`](/content/docs/cli/commands/api-keys#api-keys-get/index.html)     | Get API key            |
| [`api-keys list`](/content/docs/cli/commands/api-keys#api-keys-list/index.html)   | List API keys          |
| [`api-keys update`](/content/docs/cli/commands/api-keys#api-keys-update/index.html) | Update API key         |

Every command also takes the [global flags](/content/docs/cli/commands#global-flags/index.html).

## [api-keys create](/content/docs/cli/commands/api-keys#api-keys-create/index.html)

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.

```shell
machinemail api-keys create [flags]
```

#### [Flags](/content/docs/cli/commands/api-keys#flags/index.html)

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

#### [Examples](/content/docs/cli/commands/api-keys#examples/index.html)

```shell
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](/content/docs/cli/commands/api-keys#api/index.html)

- [`POST /v0/api-keys`](/content/docs/reference/api/api-keys#create-api-key/index.html)
- [`POST /v0/inboxes/{inbox_id}/api-keys`](/content/docs/reference/api/api-keys#create-api-key-in-inbox/index.html) with `--inbox`
- [`POST /v0/pods/{pod_id}/api-keys`](/content/docs/reference/api/api-keys#create-api-key-in-pod/index.html) with `--pod`

## [api-keys delete](/content/docs/cli/commands/api-keys#api-keys-delete/index.html)

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](/content/docs/cli/commands/api-keys#arguments/index.html)

| Field             | Description                          |
|-------------------|--------------------------------------|
| `<api-key-id>`    | Required - ID of the API key.     |

#### [Flags](/content/docs/cli/commands/api-keys#flags-1/index.html)

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

#### [Examples](/content/docs/cli/commands/api-keys#examples-1/index.html)

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

#### [API](/content/docs/cli/commands/api-keys#api-1/index.html)

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

## [api-keys get](/content/docs/cli/commands/api-keys#api-keys-get/index.html)

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](/content/docs/cli/commands/api-keys#arguments-1/index.html)

| Field             | Description                          |
|-------------------|--------------------------------------|
| `<api-key-id>`    | Required - ID of the API key.     |

#### [Flags](/content/docs/cli/commands/api-keys#flags-2/index.html)

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

#### [Examples](/content/docs/cli/commands/api-keys#examples-2/index.html)

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

#### [API](/content/docs/cli/commands/api-keys#api-2/index.html)

- [`GET /v0/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#get-api-key/index.html)
- [`GET /v0/inboxes/{inbox_id}/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#get-api-key-in-inbox/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#get-api-key-in-pod/index.html) with `--pod`

## [api-keys list](/content/docs/cli/commands/api-keys#api-keys-list/index.html)

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](/content/docs/cli/commands/api-keys#flags-3/index.html)

| Field             | Description                                   |
|-------------------|-----------------------------------------------|
| `--inbox <inbox-id>`  | Only this inbox.                           |
| `--pod <pod-id>`      | Only this pod.                             |
| `--type`              | bearer | public_key   Only this credential family.                         |
| `--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](/content/docs/cli/commands/api-keys#examples-3/index.html)

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

#### [API](/content/docs/cli/commands/api-keys#api-3/index.html)

- [`GET /v0/api-keys`](/content/docs/reference/api/api-keys#list-api-keys/index.html)
- [`GET /v0/inboxes/{inbox_id}/api-keys`](/content/docs/reference/api/api-keys#list-api-keys-in-inbox/index.html) with `--inbox`
- [`GET /v0/pods/{pod_id}/api-keys`](/content/docs/reference/api/api-keys#list-api-keys-in-pod/index.html) with `--pod`

## [api-keys update](/content/docs/cli/commands/api-keys#api-keys-update/index.html)

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](/content/docs/cli/commands/api-keys#arguments-2/index.html)

| Field             | Description                          |
|-------------------|--------------------------------------|
| `<api-key-id>`    | Required - ID of the API key.     |

#### [Flags](/content/docs/cli/commands/api-keys#flags-4/index.html)

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

#### [Examples](/content/docs/cli/commands/api-keys#examples-4/index.html)

```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](/content/docs/cli/commands/api-keys#api-4/index.html)

- [`PATCH /v0/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#update-api-key/index.html)
- [`PATCH /v0/inboxes/{inbox_id}/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#update-api-key-in-inbox/index.html) with `--inbox`
- [`PATCH /v0/pods/{pod_id}/api-keys/{api_key_id}`](/content/docs/reference/api/api-keys#update-api-key-in-pod/index.html) with `--pod`