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). Some scopes below are registered ahead of the endpoints that will use them -- the Endpoints page is authoritative for what is callable today.

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).
`widget:read`	Read widget appearance, behaviour, and embed settings.
`widget:write`	Update widget settings and purge the served widget cache.
`agents:write` sensitive	Invite, update, suspend, restore, or remove agents. An invitation creates a new person with operator-console access to every chat on this widget.
`agents:events:read`	Read an agent's activity/event log and per-agent metrics.
`departments:read`	Read departments, their agents, and their schedules.
`departments:write`	Create, update, or delete departments and their schedules.
`messengers:read`	Read which messenger and social channels are connected (never their credentials).
`messengers:write` sensitive	Connect or disconnect a messenger channel. Writes provider credentials and repoints provider-side webhook registration.
`ai:read`	Read AI assistants, their configuration, and AI alerts.
`ai:write` sensitive	Create and update AI assistants, AI settings, and AI operators. This includes the persona and system prompt the bot speaks to your customers under.
`ai:credentials:write` sensitive	Store third-party LLM provider credentials that the platform then uses for outbound calls.
`ai:apply` sensitive	Approve an improvement that rewrites a live assistant's persona/system prompt.
`kb:read`	Read knowledge-base rules and ingested sources.
`kb:write`	Create, update, or delete knowledge-base rules and ingestion sources.
`transcripts:read`	Export a chat transcript.
`account:read`	Read the owning account's profile and legal entities.
`account:write`	Update the owning account's profile and legal entities.
`billing:read`	Read balance, tariff, invoices, and payment history.
`billing:write` sensitive	Issue an invoice and change auto-renewal settings.
`partners:read`	Read partner/referral account data.
`partners:withdraw` sensitive	Request a payout of partner earnings. This moves money out of the platform.

The scopes marked sensitive above let a token act as (or hand off to) another operator on your behalf, invite a new person into your operator console, write third-party credentials, rewrite a live assistant's persona, or move money -- 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.