Tokens de API e acesso para desenvolvedores

Q: O que acontece se o meu token for comprometido?

Vá em Configurações > Tokens de API imediatamente, revogue o token comprometido e gere um novo. Atualize quaisquer serviços que dependiam do token antigo.

Atualizado em 20 de out. de 20266 min de leitura

Português

Nesta página

Tokens de API dão a código ou scripts uma forma de conversar com sua conta Deskwoot sem usar senha. Você gera um por integração (sync com CRM, dashboard custom, ferramenta interna) e escopa para só as permissões que essa integração realmente precisa. Tokens podem ser revogados a qualquer hora; revogar é instantâneo e não afeta outros tokens. Base URL é https://deskwoot.com/api/v1/ e o header de auth é Authorization: Bearer YOUR_TOKEN.

O Deskwoot oferece uma REST API que lhe dá acesso programático aos seus dados e fluxos de suporte. Seja para criar integrações personalizadas, sincronizar dados de tickets com ferramentas internas ou automatizar tarefas repetitivas, os tokens de API permitem que você se autentique com segurança sem compartilhar as suas credenciais de login. Este guia mostra como gerar tokens, fazer a sua primeira chamada de API e seguir as práticas que mantêm a sua conta segura.

A REST API é um recurso do plano Enterprise. O teste de 7 dias do Enterprise com o qual toda conta nova começa não inclui tokens de API; você precisa de um plano Enterprise ativo para criá-los e usá-los. Se você está em um plano inferior e precisa de acesso à API, será necessário estar no Enterprise. Para um panorama mais completo do que a API abrange, veja a visão geral da REST API.

Como eu gero um token de API?

Faça login na sua conta do Deskwoot e vá em Configurações > Tokens de API.
Clique em Criar token. Só administradores podem criar tokens.
Dê ao token um nome descritivo (por exemplo sincronização de CRM, produção) para que você possa identificar a finalidade dele depois.
Selecione as permissões específicas que o token deve ter. Conceda apenas os níveis de acesso de que a sua integração realmente precisa. Se quiser, escolha uma data de expiração.
Confirme e copie o token imediatamente. Por motivos de segurança, o token completo é exibido só uma vez.

Como eu uso a API?

Todas as requisições à API são feitas para a seguinte URL base:

https://deskwoot.com/api/v1/

Inclua o seu token de API no cabeçalho Authorization de cada requisição:

Authorization: Bearer YOUR_TOKEN

Exemplo de requisição

Uma chamada cURL simples para testar a sua conexão pode ser assim:

curl -H "Authorization: Bearer YOUR_TOKEN" https://deskwoot.com/api/v1/me

Se o token for válido, a API retorna o ID da sua conta e os escopos do token. Se não, você recebe um erro de autenticação. A referência completa dos endpoints está na documentação da API.

Quais são as melhores práticas?

Conceda o mínimo de acesso necessário. Atribua a cada token apenas as permissões de que ele precisa. Evite criar tokens com acesso total de administrador, a não ser que você realmente precise.
Rotacione os tokens com regularidade. Revogue periodicamente os tokens antigos e gere novos, especialmente quando membros da equipe mudam de função ou saem.
Armazene os tokens com segurança. Guarde os tokens em variáveis de ambiente ou em um gerenciador de segredos. Nunca os deixe fixos no código do lado do cliente nem os envie para o controle de versão.
Use nomes descritivos. Nomear os tokens conforme a integração ou o ambiente que eles servem torna a auditoria simples.
Monitore o uso. Revise os seus tokens ativos em Configurações > Tokens de API regularmente e exclua os que não estão mais em uso.

Como eu resolvo erros de token?

401 Unauthorized: Confira se o token foi copiado corretamente, se não foi revogado e se está incluído no cabeçalho com o prefixo Bearer.
403 Forbidden: O token pode não ter as permissões para o endpoint que você está chamando. Crie um novo token com os escopos certos e revogue o antigo. Um 403 também aparece quando o workspace não está mais no plano Enterprise.
Limite de taxa: Se você receber erros de limite de taxa, reduza a frequência com que chama a API ou adicione recuo exponencial ao seu código.

Perguntas frequentes

A REST API está disponível em todos os planos?

Não. A REST API é um recurso do plano Enterprise. Os planos pagos inferiores não a incluem, nem o teste de 7 dias do Enterprise: tokens de API exigem um plano Enterprise ativo.

Posso criar vários tokens de API?

Sim. Você pode gerar quantos tokens precisar. Recomenda-se criar um token separado para cada integração ou ambiente, para que você possa revogar um sem afetar os outros.

O que acontece se o meu token for comprometido?

Vá em Configurações > Tokens de API imediatamente, revogue o token comprometido e gere um novo. Atualize quaisquer serviços que dependiam do token antigo.

E se eu quiser que um agente de IA use a central de suporte?

Se você quer que um agente de IA externo opere o Deskwoot em vez de construir a sua própria integração, veja o servidor MCP. Ele também é um recurso do plano Enterprise e usa tokens de bot com escopo restrito.

Onde crio um token de API?

Settings → API Tokens → Create token. Escolhe um nome descritivo, seleciona os escopos, copia o token uma vez. O token só é exibido uma vez por questão de segurança.

Quais escopos existem?

Em Settings → API Tokens dá pra escolher read (tudo), write (tudo), contacts:read, contacts:write, conversations:read, conversations:write, help_center:read, help_center:write e inbound:ingest (enviar mensagens pra uma inbox de canal REST API, não incluído em write). Escopa cada token só pro que a integração precisa: privilégio mínimo bate conveniência.

O que acontece se eu perder um token?

Revoga e cria outro. Não tem recovery; o valor do token nem é guardado de forma recuperável do nosso lado, isso é intencional.

Tem rate limit?

Os limites valem por endpoint, onde o trabalho é pesado. O endpoint de mensagens de entrada aceita 120 requests por minuto por token, e os endpoints de IA são limitados por user e por conta. Bater o limite te dá 429; os endpoints de IA mandam também o header Retry-After. Precisa de limites maiores? Fala com a gente.

Posso escopar um token para uma única inbox ou time?

Não no nível de escopo. Contorno: filtra cada request para os IDs dessa inbox/time do seu lado.

Os tokens são vinculados a user ou conta?

Aos dois: o token pertence ao user que o criou, dentro de uma conta, e as ações com o token são atribuídas a esse user. Cada membro vê e revoga só os próprios tokens, e remover alguém do workspace não revoga os tokens dessa pessoa, então peça que ela revogue os tokens antes de sair. Best practice: ter um user 'service-account' dedicado dono de todos os tokens de integração.

Como rodo tokens com segurança sem downtime?

Cria o novo token, faz deploy em tudo, deixa o antigo ativo por um ciclo de deploy, depois revoga. Os dois tokens funcionam em paralelo durante a janela então nada quebra.

A API conta para minha cota de AI conversations?

Não. Ler conversas, postar resposta de agente ou gerenciar contatos pela API não usa AI conversations. AI conversations são usadas quando o Fynn ou o Copilot trabalham numa conversa.

Posso usar a API do browser?

Tecnicamente sim, mas não bote tokens em código client-side: qualquer um vendo o source pode roubar. Chamadas client-side devem passar pelo seu próprio backend que guarda o token.

Tem spec OpenAPI / Swagger?

Sim, em https://deskwoot.com/openapi.yaml. A documentação legível fica em deskwoot.com/docs/api.

Posso receber webhooks em vez de fazer polling?

Sim. Settings → Webhooks → subscreve nos eventos (nova conversa, nova mensagem, mudança de status, etc.). Cada entrega é assinada com HMAC (header X-Deskwoot-Signature); verifica a signature antes de processar.

Este guia foi útil?

Continue lendo

Perguntar ao Fynn sobre este guia

Receba uma resposta curta deste guia e do resto da Central de Ajuda.