API keys let external CRMs trigger outbound dialout without an admin JWT. They authenticate the X-API-Key path of POST /api/v1/sip/dialout (see SIP dialout). Keys live in the api_keys MongoDB collection. The API-key logic lives in the API service’s api-keys route and api-key auth module.

​
Key format & storage

_generate_api_key:
PartValue
Raw keyvx_ + secrets.token_urlsafe(24)
key_prefixfirst 7 chars (vx_ + 4) — the only visible fragment after creation
key_hashsha256(raw) hex digest
The raw key is returned only once, in the create response. CXB API stores only the SHA-256 hash and the 7-char prefix — there is no way to recover a lost key, only to delete it and issue a new one.

​
Management endpoints

All under /api/v1/api-keys, requiring admin:
MethodPathPurpose
POST“Create a key — response includes the raw key once
GET“List keys (prefix, active, expiry, last_used_at, creator) — no secret
PATCH/{key_id}Update name / is_active / expires_at
DELETE/{key_id}Permanently delete
Stored document fields: name, key_prefix, key_hash, created_by, is_active, expires_at, last_used_at, created_at, updated_at.

​
Verification at dialout

require_api_key runs when the request carries X-API-Key:
BehaviourDetail
LookupBy key_hash (SHA-256 of the presented raw key)
Inactiveis_active=false → 403 API key is inactive
Expiryexpires_at coerced to UTC (_coerce_utc_datetime, handles Z/ISO); past → 403 expired; malformed → 403 invalid expiry; None = never expires
last_used_atUpdated via asyncio.create_task — fire-and-forget, never blocks dialout; failures are logged, not raised
The /dialout route accepts either X-API-Key or an admin/super_admin Bearer JWT (require_admin_or_api_key), so the endpoint stays backward-compatible for dashboard callers.

SIP dialout

The dual-auth endpoint API keys protect.

API keys (operations)

Operator/CRM-facing key management and usage.

CRM dialout API

How CRMs call the dialout endpoint.

Users & roles

The JWT path and admin gating for key management.