Authentication and limits

API keys

Owners and admins create keys under Developers in the console. A key looks like sr_live_ followed by 32 characters and is shown once; we store only its SHA-256 hash. Send it in the Authorization header:

Authorization: Bearer sr_live_…

A key belongs to one workspace and acts for all of it — every site, like an admin who serves them all — so there is no workspace header. Keep keys on your server, never in a web page or app. Revoke a key in the console and it stops working at once.

Scopes

Each key holds only the scopes you tick. A call without the needed scope gets 403 forbidden with error.fields.scope naming it.

Scope	Allows
conversations:read	GET /v1/conversations, GET /v1/conversations/{id}
conversations:write	POST …/assign, POST …/close
messages:read	GET /v1/conversations/{id}/messages, GET /v1/offline-messages
messages:write	POST /v1/conversations/{id}/messages
visitors:read	GET /v1/visitors/{id}
visitors:write	PATCH /v1/visitors/{id}
members:read	GET /v1/members
visitors:export	POST /v1/visitors/lookup, GET /v1/visitors/{id}/export (data requests)
visitors:delete	DELETE /v1/visitors/{id} (data requests)
any	GET /v1/usage

Other endpoints (sites, team, billing, keys themselves) are for the console only and refuse keys.

Sending messages

POST /v1/conversations/{id}/messages sends:

• as your integration by default: the message shows as from your site (to the visitor) and as Integration (to agents). It does not take the conversation from the queue, so it suits bots and automatic replies. Text only.
• as an agent with "member_id": "…": the message is from that agent, and like any agent reply it takes a waiting conversation — so the key also needs conversations:write.

Limits

Limit	Value	When exceeded
Requests per key	20 per second	429 rate_limited with Retry-After
API calls per workspace	Your plan's monthly allowance (UTC month, all keys together)	402 quota_exceeded, fields.limit = api_calls_per_month
Active keys	20 per workspace	402 quota_exceeded, fields.limit = api_keys

GET /v1/usage shows this month's calls against the allowance. Refused calls are not counted. Plans without API calls (Free) cannot create keys.