bird api-keys create

Usage

Code example

bird api-keys create [flags]

Create a workspace key and receive its token once, in this response; no later call reads it back. A key can never issue or revoke another key. 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

Code example

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

# the body it prints:

Code example

{
  "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"
    }
  ]
}

Code example

# 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 <area>:<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, esim, esim_credentials, lookup, numbers, webhooks, preferences, workspace.

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

Name	Description
bird api-keys rotate	Rotate an API key

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Understand the conceptShould I use a Bird SDK or call the API directly?Follow the learning pathBuild your first integration Implementation guideSend your first email

Get an implementation brief