Public API Authentication and Tokens

The Chatfuel Public API authenticates every request with a token in the Authorization: Bearer <token> header. There are two kinds of tokens: your personal API token, called the CLI token in the dashboard, and virtual user tokens, which belong to API-only members of a single bot. Use virtual user tokens for everyday integration work and keep the personal API token for the few operations that need a real person.

How to send a token

Send the token in the Authorization header of every HTTP request:

POST /graphql HTTP/1.1
Host: panel.chatfuel.com
Authorization: Bearer 3c9e5f…
Content-Type: application/json

For GraphQL subscriptions over WebSocket, put the same value in the connection init payload as authToken:

{ "authToken": "Bearer 3c9e5f…" }

Tokens are opaque strings of 64 hexadecimal characters. Don't parse them or rely on their format. A request without a valid token can still reach the API, but every operation that needs a user fails with Unauthorized.

Personal API token vs virtual user token

Both tokens call the same endpoint and the same operations. An operation that works inside a bot gives the same result with either token as long as the role allows it. The difference is scope: a leaked personal API token exposes your whole account, while a leaked virtual user token exposes one bot with a limited role.

How to create, regenerate and revoke the personal API token

The personal API token is managed only in the Chatfuel dashboard, never through the API:

1. Open the account menu (your name or avatar) and select CLI token, or go to https://panel.chatfuel.com/integration/auth/token.
2. Click Create token and copy it. Chatfuel shows the personal API token only once.
3. To replace a lost or exposed token, click Regenerate token. The old token stops working right away, and the new one is shown once.
4. To switch the token off, click Revoke token. Everything that uses it loses access immediately.

Each account has exactly one personal API token at a time. Virtual users can't create a personal API token for themselves.

How to get and rotate a virtual user token

A virtual user token is returned once by createVirtualUser. To rotate it, call regenerateVirtualUserToken with the virtual user's member ID: the old token stops working and the response contains the new one. To revoke access completely, remove the virtual user with removeMemberFromBot or with Delete API user in the bot's teammates. All three operations need a personal API token of a bot Admin. Virtual users shows each call.

Operations that need the personal API token

A virtual user works only inside its bot and only with the Editor or Agent role. Operations that change the account, the team, channel connections or workspaces reject virtual user tokens with NotEnoughPermissions and need a personal API token. The reference pages mark them Personal token only. They are:

• Team: createVirtualUser, regenerateVirtualUserToken, removeMemberFromBot, changeBotMemberRoleV2, createBotInviteV2, botInviteDelete, leaveBot
• Bot: renameBot, deleteBot, createWorkspaceAndBot, botUpdateRolesConfig, botResetAPIToken, botSetOpenAIModel, botUnsetOpenAIModel, updateUserOpenedBotDate
• Bot settings that need the Admin role: botUpdateTimezone, botUpdateCountryCode, botUpdateIndustry, botSetLivechatAutoClosingConfig
• Channel connections: botConnectFacebookPage, botConnectInstagramAccount, botConnectTikTokAccount, botDisconnectContactScope, the botPlatformConnectionLink* and botPlatformAccessRefreshLink* mutations and the Bot.activePlatform*Links fields, fbPagesSyncForBusiness, fbPageSyncLatestPosts, whatsAppEntitiesStartRefetch, whatsAppPhoneSyncBizAppData, whatsAppPhoneSetProfileImageFile
• Workspaces and billing: all workspace* mutations, currentUser.workspace and currentUser.workspaces, Workspace.subscription, Workspace.usageStats, the billingSubscriptionUpdated subscription
• Your own account: setUserDashboardLocale, availableGoogleCalendars

How to keep tokens safe

• Keep tokens on your server, in a secret manager or encrypted environment variables. Never ship them to a browser, a mobile app or a public repository.
• Create a separate virtual user for each integration or each of your customers, so one leak affects one bot and one integration.
• Store which virtual user belongs to which of your users on your side. Chatfuel doesn't know how you map virtual users to your customers.
• Rotate a virtual user token with regenerateVirtualUserToken when someone who had access leaves, and regenerate the personal API token in the dashboard if it may have been exposed.
• Don't put tokens in URLs or logs.

Common issues

"Unauthorized"

The token is missing, mistyped, regenerated or revoked, or the virtual user was removed. Check that the header is exactly Authorization: Bearer <token>.

"NotEnoughPermissions"

The token is valid but its owner may not run this operation: a virtual user called an operation from the personal-token list above, or the virtual user's role doesn't allow it. An Agent, for example, can't edit flows. Switch to the personal API token or change the virtual user's role.

"A token already exists for your account. Regenerate it to get a new one."

Each account has one personal API token. The old one can't be shown again; click Regenerate token to get a new one.