---
title: "Public API Authentication and Tokens"
description: "Send a personal API token (CLI token) or a virtual user token as a Bearer token. Use virtual users for daily calls and the personal token for account tasks."
canonical_url: https://chatfuel.com/docs/public-api/authentication
markdown_url: https://chatfuel.com/docs/public-api/authentication.md
last_updated: 2026-10-06
lang: en
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Public API Authentication and Tokens

Send a personal API token (CLI token) or a virtual user token as a Bearer token. Use virtual users for daily calls and the personal token for account tasks.

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 [#how-to-send-a-token]

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

```http
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`:

```json
{ "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 [#personal-api-token-vs-virtual-user-token]

|             | Personal API token (**CLI token**)          | Virtual user token                                         |
| ----------- | ------------------------------------------- | ---------------------------------------------------------- |
| Belongs to  | You, a real Chatfuel user                   | A virtual user inside one bot                              |
| Sees        | Every bot and workspace you are a member of | Only its own bot                                           |
| Permissions | Your own role in each bot                   | The Editor or Agent role of the virtual user               |
| How many    | One per account                             | One per virtual user, up to 20 virtual users per bot       |
| Created in  | Dashboard → account menu → **CLI token**    | The `createVirtualUser` mutation                           |
| Lifetime    | 10 years, until revoked                     | 10 years, until regenerated or the virtual user is removed |

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 [#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 [#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](https://chatfuel.com/docs/public-api/virtual-users) shows each call.

## Operations that need the personal API token [#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 [#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 [#common-issues]

### "Unauthorized" [#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" [#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](https://chatfuel.com/docs/public-api/virtual-users).

### "A token already exists for your account. Regenerate it to get a new one." [#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.