API Key Management

API keys are created and managed from the dashboard under Account → API.

Creating a key

When you create a key you may provide:

Name (optional)

A friendly label to help you identify the key later. If you leave it blank, a memorable name is generated for you (for example swift-falcon-3f9a).

Validity (optional)

How long the key remains valid, in days. The maximum is 365 days (1 year); the default is 90 days. After this period the key expires and is rejected with key_expired.

IP restriction (optional)

A comma-separated list of IPv4/IPv6 addresses or CIDR ranges. When set, the key may only be used from those addresses. Examples:

203.0.113.5
203.0.113.5, 198.51.100.0/24, 2001:db8::/32

The full secret is displayed once, immediately after creation:

sk2_a1b2c3d4e5f6a7b8.Xq8N2yV...   ← copy this now; it will not be shown again

Only a salted hash of the secret is stored. The dashboard subsequently shows only the non-secret prefix.

Listing keys

The dashboard lists each active key with its name, prefix, expiry date, last used time, and IP restriction. Revoked keys are hidden by default.

Revoking a key

Revoking a key takes effect immediately and cannot be undone. Any request presenting a revoked key is rejected with key_revoked. Revocation is a soft delete, preserving the key’s audit history.

Limits

Each user may hold up to 25 active (non-revoked) keys at a time. Revoke unused keys before creating new ones if you reach this limit.

Security recommendations

  • Treat the secret like a password. Never commit it to source control or embed it in client-side code.

  • Scope each integration to its own key so you can revoke it independently.

  • Set an IP allowlist whenever the calling system has stable egress addresses.

  • Choose the shortest practical validity period and rotate keys regularly.

  • Revoke a key immediately if you suspect it has been exposed.

Auditing

Key creation and revocation are recorded in your organization’s audit log with the api_key target type, so you can review when keys were issued and by whom.