Bearer API Key Management

info

This page covers the newer Bearer API keys (both full-access and scoped variants). For the legacy per-user keys, see Standard API Key Management.

Bearer API keys give you per-key control over what a credential can do. You can create as many as you need, make each one full-access or scoped to specific routes, assign an expiry, and rotate or revoke them independently — without disrupting your other keys. For the request format and the difference between full-access and scoped keys, see Bearer API keys.

Manage keys in the Hub

The easiest way to manage Bearer keys is the Keys section of Settings (API Auth Credentials). There you can:

• Create a full-access or scoped key and copy its value (shown once, at creation).
• Scope a key to specific routes, or to a preset (a ready-made bundle of related routes).
• Set an optional expiration date.
• Set an optional Webhook URL (under Advanced) that overrides your account webhook for requests made with this key — see Per-key webhook URL.
• Rotate a key (replace its value; the old value stops working immediately) or revoke it.
• Assign managers — the account users allowed to view, edit, and delete that key in the Hub. The account owner always has access.

Manage keys with the partner API

The same operations are available under /api/v1/partner/settings/api-keys for programmatic management (these calls require a request signature, so a scoped key alone cannot mint a more powerful key). The full request and response details for each live in the Settings section of the API reference:

• Create an API key — full-access or scoped (returns its value once).
• Retrieve API keys list — list your active keys (?include_archived=true also returns revoked/expired keys, with their values masked).
• Retrieve an API key — fetch a single key.
• Update an API key — change its name, scopes, expiry, or managers.
• Rotate an API key — regenerate the key value.
• Revoke an API key — turn a key off.
• Available permissions — discover the routes and presets a key can be scoped to.
• Verify the calling key — check the key making the request (see Verify a key).

Per-key webhook URL

Each Bearer key (full-access or scoped) can carry its own webhook URL. When set, asynchronous results and event notifications for requests made with that key are delivered to the key's URL instead of your account-level (global) webhook. If a key has no webhook URL, delivery falls back to the account webhook configured in the Keys section.

This lets you route different integrations to different endpoints — for example, a scoped key for one product line can deliver to that team's endpoint — without touching your global webhook.

• Hub: open the key's create or edit dialog, expand Advanced, and set Webhook URL.
• Partner API: pass webhook_url when you create or update a key. Send null to clear it and fall back to the account webhook.

The URL must be a public HTTPS endpoint. Deliveries use the same signed payload format as the account webhook, so your existing webhook validation works unchanged.

note

A per-key webhook URL also counts as having webhooks enabled for that key. So a request made with a key that has its own webhook URL can receive async notifications even if your account has no global webhook configured.

Rotating a key (zero downtime)

Because you can have many independent keys, rotation is simple:

1. Create a new key (or rotate an existing one to get a fresh value).
2. Roll out the new value to every integration that uses it, and verify successful calls.
3. Revoke the old key once nothing depends on it.

caution

A revoked or rotated key stops working immediately. Verify your integrations are using the new value before revoking the old one.