bird api-keys rotate

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

Rotate an API key

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.

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

# the body it prints:

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

# 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