> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segurança do token

> Boas práticas para os tokens da API do Connecta DESK: permissões mínimas, prazo de validade, lista de IPs permitidos, rotação e o que fazer se um token vazar.

Um token da API dá acesso aos dados da empresa inteira, dentro das permissões marcadas nele. Não
existe segundo fator nem confirmação por e-mail. Qualquer pessoa que tenha o token consegue usar a
API em nome da empresa.

Esta página reúne as práticas que limitam o estrago se um token vazar ou for mal usado. O melhor
momento para decidir as permissões de um token é quando você o cria.

## Um token por integração

<Warning>
  O erro mais comum é criar um token "geral", com todas as permissões, e usar o mesmo em vários
  sistemas. Se ele vazar, você não sabe por qual sistema vazou, e ao revogá-lo todas as integrações
  param de uma vez.
</Warning>

Com um token para cada sistema que usa a API, os dois problemas somem. O nome e o `lastUsedAt`
mostram qual sistema usa cada token, e revogar um deles afeta só aquele sistema.

<Columns cols={2}>
  <Card title="Nomeie pelo sistema que usa" icon="tag">
    Use nomes como `Sincronização de contatos do ERP` ou `Relatórios noturnos do BI`. Um nome como
    "token 1" não ajuda quando alguém precisar decidir se pode revogá-lo.
  </Card>

  <Card title="Escopo mínimo" icon="shield-check">
    Marque só o que a integração usa hoje. Ampliar as permissões depois leva uns 30 segundos no
    painel. Corrigir o estrago de um token com permissões demais dá muito mais trabalho.
  </Card>
</Columns>

## O que merece atenção redobrada

Algumas permissões dão mais poder que outras. Duas pedem cuidado especial:

<AccordionGroup>
  <Accordion title="Escrita em users equivale a poder administrativo" icon="user-cog">
    Com `users: ["POST"]`, o token pode convidar pessoas para a empresa. Com `users: ["PUT"]`, pode
    alterar o perfil de quem já está nela, inclusive promover alguém a administrador. Um
    administrador, por sua vez, pode criar novos tokens.

    Dê essas permissões só a integrações de RH ou de provisionamento de acessos que precisem delas
    de verdade. Se a rotina só precisa listar os usuários, dê apenas `GET`.
  </Accordion>

  <Accordion title="DELETE não tem desfazer" icon="trash-2">
    Exclusões pela API não pedem confirmação. Se uma sincronização com defeito chamar
    `DELETE /contacts/{id}` repetidamente, não há como desfazer.

    Se a integração precisa excluir dados, deixe essa parte em uma rotina separada, com um segundo
    token e log próprio.
  </Accordion>
</AccordionGroup>

## Prazo e allowlist

<Steps>
  <Step title="Defina prazo sempre que fizer sentido">
    Tokens para um projeto com fim previsto, um teste de fornecedor ou uma prova de conceito devem
    ser criados já com data de validade. Um token sem prazo continua funcionando anos depois de o
    projeto acabar.

    Anote a data de validade junto da documentação da integração. Um token vencido recebe o mesmo
    `401` de qualquer token inválido, e sem essa anotação fica difícil descobrir por que a
    integração parou.
  </Step>

  <Step title="Restrinja o IP quando houver IP fixo">
    Com a lista de IPs permitidos (allowlist) preenchida, o token só funciona em chamadas que saem
    desses endereços. Mesmo que ele vaze, não pode ser usado de outro lugar.

    A lista aceita endereços IPv4 (`200.150.10.20`) e faixas CIDR (`191.30.0.0/16`), com até 50
    entradas.

    <Warning>
      Antes de restringir, confirme o IP de **saída** real do sistema que usa o token. Serviços em
      nuvem costumam sair por um endereço diferente do que aparece no painel do provedor, e uma
      lista errada faz a integração parar na hora.
    </Warning>
  </Step>

  <Step title="Rotacione periodicamente">
    **Rotacionar** gera um novo valor para o token e mantém o nome, as permissões e a allowlist. A
    configuração da integração continua igual e só a chave muda. O valor antigo deixa de funcionar
    na hora, então combine o momento da troca com quem cuida do sistema que usa o token.
  </Step>
</Steps>

## Onde a chave pode ficar

<Columns cols={2}>
  <Card title="Pode" icon="circle-check">
    Variável de ambiente, cofre de segredos (Vault, AWS Secrets Manager, Doppler), configuração
    cifrada do servidor.
  </Card>

  <Card title="Não pode" icon="circle-x">
    Repositório, front-end, aplicativo móvel, planilha, mensagem de chat, ticket de suporte,
    print de tela.
  </Card>
</Columns>

<Warning>
  Nunca chame a API direto do navegador ou de um app móvel. Tudo o que chega ao aparelho do usuário
  pode ser lido por ele, e a chave ficaria exposta. Faça as chamadas por um serviço seu, que guarda
  o token e libera para o app só o que aquele usuário pode fazer.
</Warning>

Tome cuidado também com os logs. Registrar a requisição inteira em modo de depuração costuma gravar
junto o header `Authorization`. Oculte esse campo antes de salvar o log.

## Se uma chave vazou

<Steps>
  <Step title="Revogue ou rotacione agora" icon="ban">
    Faça isso no painel, em **Configurações → Integrações → API**. A revogação vale na hora, sem
    período de tolerância.

    Rotacione se a integração precisa continuar funcionando. Revogue se ela pode parar.
  </Step>

  <Step title="Veja o que aquele token alcançava" icon="search">
    Abra o token e confira as permissões. Elas mostram exatamente o que pode ter sido feito com
    ele. Um token com `reports: ["GET"]`, por exemplo, dava acesso aos relatórios, mas não permitia
    alterar nenhum contato.

    O `lastUsedAt` mostra quando ele foi usado pela última vez.
  </Step>

  <Step title="Corrija a origem" icon="wrench">
    Se você só rotacionar, sem descobrir como a chave vazou, o problema pode se repetir. Verifique
    repositório, logs, prints e credenciais compartilhadas em chat, e corrija a causa antes de
    distribuir a chave nova.
  </Step>
</Steps>

## Revisão periódica

Uma vez por trimestre, abra a lista de tokens e confira cada um:

<Check>
  Ainda existe uma integração usando este token? O `lastUsedAt` mostra.
</Check>

<Check>
  As permissões ainda correspondem ao que a integração faz hoje, ou sobrou alguma de uma versão
  antiga?
</Check>

<Check>
  O prazo de validade faz sentido, ou é um token sem prazo de um projeto que já acabou?
</Check>

<Check>
  Quem criou o token ainda trabalha na empresa? O painel mostra quem criou e quem editou por
  último.
</Check>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.