Security and data

Integration with Commerce API v1 processes commerce data and customer contact details. This section collects rules that protect the key secret and the people the bot contacts.

Key secret protection

We show the key secret only once, when the key is created. Treat it like a production password.

• Store the secret server-side only (secrets manager, environment variables), never in a repository, frontend code, or client app.
• Do not put the secret or signature in the URL — headers only.
• Sign requests on the backend; browsers and mobile apps must not access the secret.
• In documentation and screenshots, always mask the key ID: cba_test_••••••••.
• Rotate keys periodically and after any suspected leak — see rotation with an overlap window in Authentication.

TLS and transmission integrity

All API communication and webhook delivery use TLS. On the webhook receiver side:

• accept HTTPS connections only,
• verify the signature of every incoming event before processing it (details in Webhooks),
• reject events with timestamps outside the accepted window to limit replay risk.

Least privilege

Scopes use deny-by-default. Grant a key only the scopes that integration actually uses, and split keys by task (e.g. one key for catalog sync, one for reading results).

• Catalog import only: catalog:write (without orders:*).
• Results receiver only: results:read.
• Customer data erasure requires a separate, narrow customers:erase scope.

The full scope list is in Authentication.

Personal data and redaction

• Minimization — send only data needed for the conversation (e.g. phone in E.164, first name for personalization). Do not send sensitive data the bot does not need.
• Log redaction — do not log phone numbers, conversation content, or the secret. For diagnostics, correlation_id from the error response is enough (see Errors).
• No secrets in URLs — keep sensitive and auth data in the body or headers, never in query strings that end up in intermediary server logs.

Consent and DNC take precedence

The bot calls only according to applicable contact consent. Consent status and DNC (do-not-call) lists are authoritative over data sent through the API — passing a contact (e.g. a repurchase intent) does not override missing consent or a DNC entry. Update consent status on your side and do not pass contacts that withdrew consent into conversations.

Reporting vulnerabilities

If you suspect a security flaw or key leak, revoke the key immediately via rotation and contact support. Do not include the secret or PII in the report — provide correlation_id, timestamp, and description.