Authentication. One token per system, with only what it needs.
Every request carries an API token. Account owners create tokens in the dashboard and choose what each one may do.
By Santhul Joseph, AI EngineerUpdated
Create a token
An account owner opens Settings → API in the dashboard (https://get.simplyboost.io/settings/api) and selects Create token. A token has:
- A name, so you can tell tokens apart, for example the system that uses it.
- Permissions (scopes): what it may read and change. See the table below.
- Chatbots: all chatbots, or only the ones you pick. Other chatbots answer
404. - An expiry: 30, 90 or 365 days, or never.
The token is shown once, when it is created. Store it in your server's secret store. SimplyBoost keeps only a hash and cannot show it again.
Send it with every request
curl https://get-api.simplyboost.io/api/v1/me \
-H "Authorization: Bearer $SIMPLYBOOST_TOKEN"GET /me needs no permission, so any valid token can check itself. It returns the token's name, scopes, chatbots and expiry, and the account it belongs to.
{
"ok": true,
"data": {
"user": { "id": "…", "email": "owner@studiolicht.nl", "fullName": "Sanne de Vries" },
"team": { "id": "…", "name": "Studio Licht", "plan": "pro" },
"token": {
"id": "…",
"name": "CRM sync",
"scopes": ["conversations:read", "conversations:write", "leads:read"],
"chatbotIds": [],
"expiresAt": "2027-01-05T09:00:00+00:00"
}
},
"meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}Permissions
| Scope | Allows |
|---|---|
account:read | Read the account, usage and limits. |
chatbots:read | List and read chatbots. |
conversations:read | List and read conversations and their messages. |
conversations:write | Send messages, take over, reply, hand back to the chatbot, resolve and reopen. |
leads:read | List and read leads. |
leads:write | Update leads. |
leads:delete | Delete leads. |
knowledge:read | List and read knowledge sources. |
knowledge:write | Add, update and refresh knowledge sources. |
knowledge:delete | Delete knowledge sources. |
webhooks:read | List webhook endpoints. |
webhooks:write | Add, remove and test webhook endpoints. |
A request the token is not allowed to make returns 403 with the code insufficient_scope, and error.details.requiredScope names the scope it needs.
Rotate and revoke
- Rotate issues a new secret with the same name, permissions, chatbots and lifetime. The old secret stops working at once.
- Revoke stops a token for good.
- A token also stops working when the person who created it leaves the account.
Never put a token in a website, a mobile app or anything a visitor can download. Call the API from your server. For a chat on your website, use the SimplyBoost chat widget.