ConnectWiz API
SM AIBOT v2 is a multi-tenant (single database + Postgres Row-Level Security) customer communication and CRM platform.
This document is the single source of truth for the HTTP contract. The
shared TypeScript types in @smaibot/ts-contracts and the rendered API
reference are generated from this file. When the API changes, update this
spec first, then regenerate the contracts.
Authentication
The first-party admin SPA authenticates with Sanctum cookie / session (stateful) auth:
GET /sanctum/csrf-cookieto obtain theXSRF-TOKENcookie.POST /api/login(or/api/register) with credentials — the response sets the session cookie.- Subsequent requests send the session cookie automatically and echo the
CSRF token in the
X-XSRF-TOKENheader.
Server-to-server / third-party integrations use a Bearer token (Sanctum
personal access token) via the Authorization: Bearer <token> header.
Tenancy
The tenant is never taken as a raw id from the client. For authenticated requests it is derived from the signed-in user. For public/pre-auth requests (login, register, password reset) it is resolved from the subdomain / slug.
Errors
All error responses share the common Error envelope (see the Schemas
section of this reference). Validation failures (HTTP 422) additionally
include a field-keyed errors map, matching Laravel's validation error
shape.
Rate limiting
Responses to throttled endpoints include X-RateLimit-Limit,
X-RateLimit-Remaining and (on 429) Retry-After headers. Limits are
applied per-tenant and, for auth endpoints, per-credential.
Localization
Send Accept-Language: en or Accept-Language: tr to negotiate the
response language. Authenticated users' stored locale takes precedence,
then the tenant default, then Accept-Language, then en.
Authentication
- API Key: cookieAuth
- HTTP: Bearer Auth
- HTTP: Bearer Auth
- HTTP: Bearer Auth
- API Key: SiteKey
- HTTP: Bearer Auth
- HTTP: Bearer Auth
Sanctum stateful SPA auth. The session cookie is set by /api/login or
/api/register. Mutating requests must also send the CSRF token from
the XSRF-TOKEN cookie in the X-XSRF-TOKEN header.
Security Scheme Type: | apiKey |
|---|---|
Cookie parameter name: | smaibot_session |
Sanctum personal access token for server-to-server / third-party
integrations: Authorization: Bearer <token>.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
The SHARED secret between this API and our own media sidecar
(WEBRTC_BRIDGE_TOKEN) — NOT a user credential and not a Sanctum token.
It authenticates the sidecar's server-to-server callbacks; the tenant is
resolved from the opaque routing context the sidecar echoes back, never
from the request path.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
A workspace's own SERVER key (cwz_…), created under Settings →
Catalogue → Keys for your own storefront and shown once. Scoped per
verb: catalogue:read, orders:read, orders:write (commerce API) and
tools:run (Tools API). Keep it on a server — never in a browser or an
app bundle; it is not the public widget key.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
A connected web site's PUBLIC browser key (pk_…, doc 105 §4.2) —
also accepted as key in the body or the query string. Not a secret:
it sits in the site's HTML. It writes touches and nothing else, and
only from the site's own domains (Origin / Referer). The
workspace's chat WIDGET key works the same way (DA-2b) for the sites
linked to the widget (widget_linked), from their domains only.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-CW-Key |
A connected web site's SERVER key (sk_…, scope forms:submit),
created under Settings → Integrations → Website and shown once. Keep it
on the site's server, never in a page.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
Anonymous visitor session credential for the PUBLIC chat widget (NOT a
staff token). The signed, self-contained token is issued by
POST /api/widget/session and presented as Authorization: Bearer <token> (or the X-Widget-Session header). It scopes the visitor to
exactly one {tenant, contact, conversation}; it grants no other access.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | opaque |
License