Authentication

How the Platform API agent token and the APIchat channel token work, where to find each, and what they grant.

Landbot exposes two HTTP APIs with two different tokens. Picking the wrong one is the most common cause of 401 Unauthorized.

Note New to the dashboard? The Help Center's Account settings walks through where these live in the UI.

Both tokens go in the same header:

Authorization: Token <your_token>
Content-Type: application/json

The header name is Authorization. The value is the literal word Token, a space, then the token string. There's no Bearer prefix and no Basic-auth pair.

Agent token (Platform API)

The agent token represents you, the human user. It grants the same access through the API that you have in the dashboard.

• Find it: app.landbot.io/gui/settings/account.
• Scope: every channel, every customer, every bot in the workspace — the API has no narrower permission model. If you can see it in the dashboard, the token can read or modify it.
• One per agent. Each agent in your workspace has their own token; calls made with it are attributed to that agent (e.g. agent_id fields on assigned conversations).

Warning Treat the agent token like a password. Anyone holding it can impersonate you against the entire workspace. Don't commit it to source, don't paste it in chat tools, don't embed it in client-side code.

Use the agent token for: managing customers and channels, sending messages, assigning conversations, registering webhooks, reading/writing custom fields.

Channel token (APIchat)

The channel token represents one APIchat channel. It's the credential a middleware service uses to push messages from an external platform (Telegram, Slack, custom mobile app, ...) into a specific Landbot channel.

• Find it: open the APIchat channel in the dashboard; the token is shown in the channel's configuration panel.
• Scope: that channel only. The token can send messages to customers on this channel, create and update customers within it, and look up the agents assigned to it. It cannot reach other channels or workspace-level resources.
• One per channel. If you have three APIchat channels, you have three independent tokens.

Use the channel token for: anything in the APIchat reference.

Webhook tokens

When you register a message hook on a channel, you can optionally provide a token. Landbot sends this back in the Authorization header on every webhook delivery, so your endpoint can verify the request originated from Landbot.

This isn't an API key in the conventional sense — it's a shared secret you choose, set on the hook, and check on incoming requests. Use a long random string. Rotate by updating the hook (or deleting and recreating it).

Picking the right one

Is the path under api.landbot.io  → Agent token
Is the path under chat.landbot.io → Channel token
Is the request coming from Landbot to your server → Verify it matches the webhook token you set

Best practices

• Don't commit tokens to source control. Use environment variables (LANDBOT_AGENT_TOKEN, LANDBOT_CHANNEL_TOKEN) or your platform's secret store.
• Don't ship tokens to a browser. The Platform API and APIchat are server-to-server APIs. Browser-side code should call your backend, which calls Landbot.
• Rotate periodically. Treat token rotation as routine maintenance, especially after personnel changes.
• One token per service. If two systems share a token and one is compromised, you don't know which.
• HTTPS only. Both APIs reject plain HTTP; never proxy them through a non-TLS hop.