--- title: "Autenticação e tokens da Public API" description: "Envie um token de API pessoal (CLI token) ou um token de usuário virtual como token Bearer. Use usuários virtuais no dia a dia e o token pessoal para a conta." canonical_url: https://chatfuel.com/pt/docs/public-api/authentication markdown_url: https://chatfuel.com/pt/docs/public-api/authentication.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Autenticação e tokens da Public API Envie um token de API pessoal (CLI token) ou um token de usuário virtual como token Bearer. Use usuários virtuais no dia a dia e o token pessoal para a conta. A Public API do Chatfuel autentica cada requisição com um token no cabeçalho `Authorization: Bearer `. Existem dois tipos de token: o seu **token de API pessoal**, chamado de **CLI token** no painel, e os **tokens de usuários virtuais**, que pertencem a membros de um único bot que usam apenas a API. Use tokens de usuários virtuais no trabalho de integração do dia a dia e reserve o token de API pessoal para as poucas operações que exigem uma pessoa real. ## Como enviar um token [#como-enviar-um-token] Envie o token no cabeçalho `Authorization` de toda requisição HTTP: ```http POST /graphql HTTP/1.1 Host: panel.chatfuel.com Authorization: Bearer 3c9e5f… Content-Type: application/json ``` Para assinaturas GraphQL via WebSocket, coloque o mesmo valor no payload de inicialização da conexão como `authToken`: ```json { "authToken": "Bearer 3c9e5f…" } ``` Os tokens são strings opacas de 64 caracteres hexadecimais. Não faça parse deles nem dependa do formato. Uma requisição sem um token válido ainda pode chegar à API, mas toda operação que precisa de um usuário falha com `Unauthorized`. ## Token de API pessoal vs. token de usuário virtual [#token-de-api-pessoal-vs-token-de-usuário-virtual] | | Token de API pessoal (**CLI token**) | Token de usuário virtual | | ------------- | -------------------------------------------------- | ------------------------------------------------------------- | | Pertence a | Você, um usuário real do Chatfuel | Um usuário virtual dentro de um bot | | Vê | Todos os bots e workspaces dos quais você é membro | Apenas o próprio bot | | Permissões | A sua própria função em cada bot | A função Editor ou Agent do usuário virtual | | Quantidade | Um por conta | Um por usuário virtual, até 20 usuários virtuais por bot | | Onde é criado | Painel → menu da conta → **CLI token** | A mutação `createVirtualUser` | | Validade | 10 anos, até ser revogado | 10 anos, até ser regenerado ou o usuário virtual ser removido | Os dois tokens chamam o mesmo endpoint e as mesmas operações. Uma operação que funciona dentro de um bot dá o mesmo resultado com qualquer um dos tokens, desde que a função permita. A diferença é o escopo: um token de API pessoal vazado expõe toda a sua conta, enquanto um token de usuário virtual vazado expõe um único bot com uma função limitada. ## Como criar, regenerar e revogar o token de API pessoal [#como-criar-regenerar-e-revogar-o-token-de-api-pessoal] O token de API pessoal é gerenciado somente no painel do Chatfuel, nunca pela API: 1. Abra o menu da conta (seu nome ou avatar) e selecione **CLI token**, ou acesse `https://panel.chatfuel.com/integration/auth/token`. 2. Clique em **Create token** e copie-o. O Chatfuel mostra o token de API pessoal apenas uma vez. 3. Para substituir um token perdido ou exposto, clique em **Regenerate token**. O token antigo para de funcionar na hora, e o novo é exibido uma única vez. 4. Para desativar o token, clique em **Revoke token**. Tudo o que o usa perde o acesso imediatamente. Cada conta tem exatamente um token de API pessoal por vez. Usuários virtuais não podem criar um token de API pessoal para si mesmos. ## Como obter e rotacionar o token de um usuário virtual [#como-obter-e-rotacionar-o-token-de-um-usuário-virtual] O token de um usuário virtual é retornado uma única vez por `createVirtualUser`. Para rotacioná-lo, chame `regenerateVirtualUserToken` com o ID de membro do usuário virtual: o token antigo para de funcionar e a resposta contém o novo. Para revogar o acesso por completo, remova o usuário virtual com `removeMemberFromBot` ou com **Delete API user** nos membros da equipe do bot. As três operações precisam do token de API pessoal de um Admin do bot. [Usuários virtuais](https://chatfuel.com/pt/docs/public-api/virtual-users) mostra cada chamada. ## Operações que precisam do token de API pessoal [#operações-que-precisam-do-token-de-api-pessoal] Um usuário virtual só funciona dentro do seu bot e só com a função Editor ou Agent. Operações que alteram a conta, a equipe, as conexões de canais ou os workspaces rejeitam tokens de usuários virtuais com `NotEnoughPermissions` e precisam de um token de API pessoal. As páginas de referência as marcam como **Somente token pessoal** (Personal token only). São elas: * **Equipe:** `createVirtualUser`, `regenerateVirtualUserToken`, `removeMemberFromBot`, `changeBotMemberRoleV2`, `createBotInviteV2`, `botInviteDelete`, `leaveBot` * **Bot:** `renameBot`, `deleteBot`, `createWorkspaceAndBot`, `botUpdateRolesConfig`, `botResetAPIToken`, `botSetOpenAIModel`, `botUnsetOpenAIModel`, `updateUserOpenedBotDate` * **Configurações do bot que exigem a função Admin:** `botUpdateTimezone`, `botUpdateCountryCode`, `botUpdateIndustry`, `botSetLivechatAutoClosingConfig` * **Conexões de canais:** `botConnectFacebookPage`, `botConnectInstagramAccount`, `botConnectTikTokAccount`, `botDisconnectContactScope`, as mutações `botPlatformConnectionLink*` e `botPlatformAccessRefreshLink*` e os campos `Bot.activePlatform*Links`, `fbPagesSyncForBusiness`, `fbPageSyncLatestPosts`, `whatsAppEntitiesStartRefetch`, `whatsAppPhoneSyncBizAppData`, `whatsAppPhoneSetProfileImageFile` * **Workspaces e cobrança:** todas as mutações `workspace*`, `currentUser.workspace` e `currentUser.workspaces`, `Workspace.subscription`, `Workspace.usageStats`, a assinatura `billingSubscriptionUpdated` * **A sua própria conta:** `setUserDashboardLocale`, `availableGoogleCalendars` ## Como manter os tokens seguros [#como-manter-os-tokens-seguros] * Mantenha os tokens no seu servidor, em um gerenciador de segredos ou em variáveis de ambiente criptografadas. Nunca os envie para um navegador, um app móvel ou um repositório público. * Crie um usuário virtual separado para cada integração ou para cada um dos seus clientes, para que um vazamento afete um único bot e uma única integração. * Registre do seu lado qual usuário virtual pertence a qual dos seus usuários. O Chatfuel não sabe como você associa usuários virtuais aos seus clientes. * Rotacione o token de um usuário virtual com `regenerateVirtualUserToken` quando alguém que tinha acesso sair, e regenere o token de API pessoal no painel se ele puder ter sido exposto. * Não coloque tokens em URLs nem em logs. ## Problemas comuns [#problemas-comuns] ### "Unauthorized" [#unauthorized] O token está ausente, foi digitado errado, regenerado ou revogado, ou o usuário virtual foi removido. Confira se o cabeçalho é exatamente `Authorization: Bearer `. ### "NotEnoughPermissions" [#notenoughpermissions] O token é válido, mas o dono dele não pode executar esta operação: um usuário virtual chamou uma operação da lista de token pessoal acima, ou a função do usuário virtual não permite. Um Agent, por exemplo, não pode editar fluxos. Troque para o token de API pessoal ou [altere a função do usuário virtual](https://chatfuel.com/pt/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] Cada conta tem um único token de API pessoal. O antigo não pode ser exibido de novo; clique em **Regenerate token** para obter um novo.