Authentication & Scopes

Authentication scheme

There are three distinct authentication paths, depending on who is calling whom:

Your system → Smartbtn (REST API calls): every request carries Authorization: Bearer <token>. The token resolves server-side to a widget-scoped identity and its granted scopes; access is deny-by-default -- a request without the required scope is rejected with 403. Each token is also subject to its own rate limit, reported via X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset response headers.
Smartbtn → your system (webhooks / external AI operator): outgoing requests are signed with a per-tenant secret and carry an X-Smartbtn-Signature: sha256=<signature> header so you can verify the body was sent by Smartbtn and not tampered with in transit. An optional bearer credential may be included as well if your integration requires one.
Your external AI operator → Smartbtn (async reply callback): the async-reply endpoint uses its own signed frame, pinned to your AI-operator identity and widget, keyed by a durable causation id rather than a short-lived nonce -- see Endpoints for the request shape.

Never put a token in the URL (e.g. ?api_token=...) -- URLs are logged in more places than headers are. Always use the Authorization header.

Scopes

Every token carries an explicit list of scopes. A request only succeeds if the token's scopes include the scope required by the endpoint being called (see the per-endpoint scope column on the Endpoints page).

Scope	Grants
`chats:read`	Read chats and their metadata.
`chats:write`	Close, transfer, or request a rating for a chat.
`messages:read`	Read a chat's message history.
`messages:write`	Send messages, typing indicators, and read receipts as an agent.
`contacts:read`	Read contacts.
`contacts:write`	Update contact fields and attributes.
`agents:read`	Read agent/operator info and presence.
`tags:read`	Read tags.
`tags:write`	Attach tags to a contact.
`files:read`	Download a previously uploaded file.
`files:write`	Upload a new file.
`stats:read`	Read aggregate chat/message/rating statistics.
`channels:read`	Read a custom channel's online status.
`channels:write`	Deliver an inbound message on a custom channel.
`webhooks:read`	List your webhook subscriptions.
`webhooks:write`	Create, delete, or redeliver a webhook subscription.
`responder:inject` sensitive	Inject a reply into a live chat as an external AI operator/bot.
`responder:escalate` sensitive	Escalate a chat from an external AI operator/bot to a human agent.
`channels:register` sensitive	Register a new custom channel (gated to installed apps only).

The three scopes marked sensitive above let a token act as (or hand off to) another operator on your behalf -- grant them to a self-issued token only if you actually need that capability.

Signature rotation

The outbound signature header is versioned independently of the API path version, e.g. X-Smartbtn-Signature: sha256=v1:<hex hmac>. When you rotate your per-tenant signing secret, both the old and the new secret remain valid for a short overlap window so in-flight deliveries signed with the old secret still verify -- there is no moment where every delivery fails. Revoking a token or secret, on the other hand, takes effect immediately.

Keeping credentials safe

Treat your API token and any webhook signing secret as passwords: never commit them to source control, never log them, and never pass a token as a URL query parameter. If a token or secret leaks, contact support to revoke it and have a new one issued -- a compromised credential cannot be "changed" in place, only replaced.