Authentication
Which token each Landbot API takes, where to find it, what it can do, and what a rejected token looks like.
Landbot's HTTP APIs take one of two tokens. Both go in the Authorization header as the word Token, a space, and the token:
Authorization: Token YOUR_AGENT_TOKEN
Content-Type: application/json
| API | Host | Token | Where to find it |
|---|---|---|---|
| Platform API, Bots API, AI Agents API, Channels API | api.landbot.io |
Agent token | app.landbot.io/gui/settings/account |
| APIchat | chat.landbot.io |
Channel token | The APIchat channel's settings in the dashboard |
The MCP server signs in with OAuth instead, so there is no token to copy.
Note New to the dashboard? The Help Center's Account settings shows where these live in the UI.
Agent token
The agent token belongs to one agent in your workspace. Every request made with it acts as that agent, with the permissions of that agent's role.
- A request your agent's role doesn't allow answers
403with{"errors": {"token": ["You don't have enought permissions"]}}. - Conversations the API assigns are assigned to that agent. Sending a message to an unassigned customer assigns the customer to the token's agent.
- Each agent has their own token.
Use the agent token to manage customers and channels, send messages, assign conversations, register message hooks, read and write Fields, and build bots through the Bots API.
Warning Treat the agent token like a password. Anyone holding it can do everything that agent can do. Keep it out of source control, chat tools and client-side code.
Channel token
The channel token belongs to one APIchat channel. Your middleware uses it to push messages from an external platform (Telegram, Slack, a mobile app) into that channel.
The token can send messages to customers on its channel, create and update customers in it, and read the agents of its workspace. It can't reach other channels. Each APIchat channel has its own token.
Use the channel token for everything in the APIchat reference.
Authentication errors
The Platform API, Bots API, AI Agents API and Channels API answer a missing or bad agent token with 401:
| Request | Response body |
|---|---|
No Authorization header. On the Platform API, also any scheme other than Token, such as Bearer |
{"detail": "Authentication credentials were not provided."} |
Token followed by an unknown token |
{"detail": "Invalid token."} |
Token with nothing after it |
{"detail": "Invalid token header. No credentials provided."} |
| A token whose agent has been deactivated | {"detail": "User inactive or deleted."} |
APIchat answers a missing or bad channel token with 403, never 401:
| Request | Response body |
|---|---|
No Authorization header |
{"detail": "Authentication credentials were not provided."} |
Token followed by an unknown token, or an agent token |
{"detail": "Invalid token."} |
| The token of an APIchat channel that is turned off or deleted | {"detail": "Channel inactive or deleted."} |
See Errors for every other status.
IDs in paths
Platform API paths take numeric IDs, such as /customers/529094641/. A customer UUID or any other string in that place matches no route and answers 404. APIchat paths take the customer token you chose or Landbot generated, such as /send/my-customer-42/. See Key concepts for which ID goes where.
Good practice
- Read tokens from environment variables (
LANDBOT_AGENT_TOKEN,LANDBOT_CHANNEL_TOKEN) or your platform's secret store. - Call Landbot from your server. The Platform API and APIchat are server-to-server APIs, so browser code should call your backend instead.
- Give each service its own agent and token, so you can tell which one leaked if one does.
- Rotate tokens after someone with access leaves.
Verifying requests Landbot sends to you is covered in Webhooks.
