callbotagent.aiDocs
v1 · Contract draft
ENPL
Open dashboard
Preview

Preview documentation. Description and screenshots come from the dashboard mockup — final values and limits will be confirmed when the production console launches.

API key generation and rotation

A Commerce API key is a pair: public key ID (sent in X-CBA-Key-Id) and secret signing secret (for HMAC only, never as a Bearer token). The secret is shown only once — on create or rotation.

Where to do it

  1. Dashboard → API Console (/dashboard/developer).
  2. API Keys tab (or "Manage keys" from Overview).
  3. Set the environment context to Test or Live (segmented control in the console header).

Key list Key list with cba_test_••••XXXX hint, scopes, expiry, and lifecycle status.

Create a key

The Create key button opens a form:

Field Meaning
Name Operational label, e.g. partner-staging
Environment Test or Live — the key works only in the selected context
Scopes Deny-by-default; select only what the integration needs
Expiration e.g. 90 days (recommended), 1 year, or no date
IP allowlist Optional CIDR; empty = no IP restriction

Create key form Create key: name, Test/Live, scopes, expiry, IP allowlist.

Typical set to start order integration:

  • orders:write
  • catalog:write
  • results:read

Add webhooks:write only when configuring the receiver endpoint.

Reveal-once (secret shown once)

After creation, a modal shows:

  1. Key ID — for the X-CBA-Key-Id header (can be copied later from the list).
  2. Signing secret — save immediately in a secrets manager / CI.
  3. Confirmation checkbox ("I saved the secret…") — Done is active only after checking it.

After closing, the secret cannot be displayed again. The only path is Rotate.

Secret reveal-once Reveal-once: key ID + secret + required confirmation before Done.

Rotation and revoke

Action Behavior
Rotate New secret (reveal-once) + overlap window for the old key (e.g. 24 h), then the old key stops working
Revoke Immediate invalidation; confirmation with reason; subsequent requests → 401 invalid_signature

List statuses: active, expiring, stale, expired, revoked, compromised. A banner warns about keys close to expiry.

After creating a key

  1. Sign requests with HMAC — Authentication.
  2. Send your first POST /orders — Quick start.
  3. Or test in Playground (Validate / Sandbox Send) in the Console.

Related