# `bird api-keys create`

## Usage

```bash
bird api-keys create [flags]
```

## Description

Create an API key

Create a workspace key and receive its token once, in this response; no later call reads it back. Scopes are limited to the data plane, so a key can never issue or revoke another one. Expiry is fixed at creation, and `cidrs` is applied in the same transaction, so an invalid range fails the whole call instead of leaving the key unrestricted.

Build the request from flags, a JSON ApiKeyCreate body via --body-file ("-" reads
stdin), or both — a flag overrides the matching body field. Run --example to
print a ready-to-edit body, or --dry-run to print the resolved request without
sending it.

## Examples

```bash
# print the body shape (no credentials needed)
bird api-keys create --example

# the body it prints:
```

```json
{
  "cidrs": ["203.0.113.0/24", "198.51.100.14/32"],
  "expires_at": "2027-01-01T00:00:00Z",
  "name": "Email operations production key",
  "scopes": [
    {
      "level": "read",
      "scope": "emails"
    }
  ]
}
```

```bash
# a key that can send email and read its own sending domains
bird api-keys create --name "Email ops key" --scope emails:write --scope domains:read

# preview the request without minting a key
bird api-keys create --name "Email ops key" --scope emails:write --expires-at 2027-01-01T00:00:00Z --dry-run
```

## Options

#### Key

| Name                | Description                                                                                                                                                                                                                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--name`            | A label for the key, shown wherever it is listed. Names do not have to be unique, and the name has no effect on what the key can do.                                                                                                                                                                     |
| `--scope <v1,v2,…>` | Permission as &lt;area>:&lt;level>. Repeatable, or comma-separated. Levels: read, write. Areas: emails, email_management, email_marketing, domains, realtime, sms, sms_management, verify, whatsapp, whatsapp_management, voice, voice_management, mailbox, mailbox_management, assets, lookup, numbers. |

#### Restrictions

| Name               | Description                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--expires-at`     | When the key stops working (RFC 3339, e.g. 2027-01-01T00:00:00Z). Omit for a key that never expires; the expiry cannot be changed afterwards. |
| `--cidr <v1,v2,…>` | Source IP range the key is restricted to (CIDR). Repeatable, or comma-separated. Omit for a key with no IP restriction.                       |

#### Request

| Name                | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `--body-file`       | Read the JSON request body from this file; "-" reads stdin   |
| `--example`         | Print a complete example request body, then exit             |
| `--dry-run`         | Print the resolved request without sending it, then exit     |
| `--idempotency-key` | Deduplication key; a retry with the same key won't act twice |

#### Options

| Name                | Description                                      |
| ------------------- | ------------------------------------------------ |
| `--response-schema` | Print the fields this command returns, then exit |