bird api-keys create

Usage

Przykład kodu

bird api-keys create [flags]

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

Przykład kodu

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

# the body it prints:

Przykład kodu

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

Przykład kodu

# 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, 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