Key management

Learn how to create new API keys or rotate your keys.

This guide explains how to manage API keys for your region. You can create new keys, rotate existing ones, and safely revoke keys that are no longer needed. You can use any of your existing API keys to do so.

API keys are always scoped to a region. To manage keys, you must first know your region’s internal identifier.

Determining your region ID

Before managing API keys, retrieve your region details using the authenticated region endpoint:

GET /auth/regions/me

This endpoint returns information about the currently authenticated region, including its internal id. You will use this id when creating or deleting API keys.

Creating a new API key

To create a new API key for a region, use:

POST /auth/region/api-keys

Provide a description to document the key’s purpose, such as “CRM integration” or “Sandbox testing”.

Listing existing API keys

API keys associated with a region are returned as part of the region object. You can inspect existing keys by calling:

GET /auth/regions/me

The response includes all API keys for the region, each with:

• An internal key ID
• A token preview
• Metadata such as creation and update timestamps

The full secret value is never returned for existing keys.

Rotating API keys

API keys do not expire automatically. To rotate a key safely:

This approach avoids downtime and allows gradual rollout across multiple systems.

Deleting an API key

To revoke an API key, use:

DELETE /auth/region/api-keys/{id}

Where:

{id} is the internal identifier of the API key.

Deletion is prevented if the key is the only remaining API key for the region. Each region must always have at least one active API key.

Best practices

• Create separate API keys per integration or environment.
• Use clear descriptions to document each key’s purpose.
• Store API keys securely and never commit them to source control.
• Rotate keys periodically or immediately if you suspect compromise.
• Use the sandbox environment for testing whenever possible.