bird api-keys rotate

Usage

Code example

bird api-keys rotate <api-key-id> [flags]

Replace an existing key and receive the new token once, in this response; no later call reads it back. The replacement carries the source key's name and IP restrictions, and its permissions unless you pass a new set, but never its expiry: the replacement never expires and no later call can add one. The previous key keeps working for the grace period, 24 hours by default, or until its own earlier expiry if it had one, since rotating never extends a key's life; grace_period: 0 revokes it immediately. A key rotates only once, and a revoked key cannot be rotated at all, so both return 409; an Idempotency-Key is what makes a retry replay the first call's token rather than hit that conflict.

Build the request from flags, a JSON ApiKeyRotate 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.

This is destructive and cannot be undone; pass --yes to confirm.

Examples

Code example

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

# the body it prints:

Code example

{
  "grace_period": "24h",
  "scopes": [
    {
      "level": "read",
      "scope": "emails"
    }
  ]
}

Code example

# rotate with the default 24-hour overlap, carrying the permissions over
bird api-keys rotate key_123 --yes

# cut over immediately, revoking the leaked key with no overlap
bird api-keys rotate key_123 --grace-period 0 --yes

# rotate and add a permission only a fresh key can be granted
bird api-keys rotate key_123 --scope emails:write --scope voice:write --yes

Options

Rotation

Name	Description
--grace-period	How long the previous key keeps working, as a duration such as 24h or 30m. Defaults to 24h. Pass "0" to revoke it immediately, which cuts over with no overlap.
--scope <v1,v2,…>	Permission the replacement carries, as <area>:<level>. Repeatable, or comma-separated. Omit to carry the current key's permissions over unchanged; passing any replaces the whole set. 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.

Name

Description

--grace-period

How long the previous key keeps working, as a duration such as 24h or 30m. Defaults to 24h. Pass "0" to revoke it immediately, which cuts over with no overlap.

--scope <v1,v2,…>

Permission the replacement carries, as <area>:<level>. Repeatable, or comma-separated. Omit to carry the current key's permissions over unchanged; passing any replaces the whole set. 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.

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

Safety

Name	Description
--yes	Confirm a destructive action (required; the CLI never prompts)

Options

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

Name	Description
bird api-keys create	Create an API key