Migre para Tokens com Escopo

Tokens legados referem-se a tokens criados antes do lançamento dos tokens com escopo da impact.com em junho de 2025. Se você atualmente usa tokens legados para autenticar com as APIs da impact.com, é hora de migrar para tokens com escopo.

Tokens legados concedem amplo acesso a todas as APIs voltadas ao cliente, o que apresenta riscos significativos de segurança e operacionais. Tokens com escopo oferecem uma alternativa mais segura e fácil de gerenciar. Leia mais sobre Melhores práticas para tokens com escopo.

Etapas da migração

1. Avalie suas integrações atuais

Primeiro, identifique todas as integrações existentes (apps, scripts ou serviços) que usam um token legado. Antes de criar novos tokens, você deve entender o que pode mudar quando fizer a troca para uma versão mais recente da API.

Comece listando cada integração e registrando sua função, os endpoints específicos que ela acessa, os tipos de ações que executa (leitura, gravação ou ambos) e quem é o proprietário ou mantém a integração.

Preste muita atenção a quaisquer mudanças que quebrem a compatibilidade entre versões da API. Você deve:

• Revise os payloads das suas requisições, pois novas versões podem renomear campos, alterar tipos de dados ou exigir novos campos. Estruturas de dados incompatíveis são uma fonte comum de erros em tempo de execução.
• Examine a estrutura dos payloads de resposta, pois os campos podem ser renomeados, removidos ou aninhados de forma diferente, o que exigirá atualizações na lógica do seu aplicativo para ler respostas da API.

2. Gere um novo token com escopo

Assim que sua avaliação estiver concluída, você pode gerar um novo token com escopo. Use nosso guia para criar tokens com escopo, seja você um marca, parceiro, ou agência.

Com base na sua avaliação, liste todos os endpoints que sua integração usa e mapeie cada operação, como GET, POST, PUT, ou DELETE para o respectivo escopo mínimo na nova versão da API. Quando você criar o token, atribuirá apenas esses escopos granulares, adaptando-o às necessidades específicas da integração.

Selecione a versão de API de destino ao gerar o token, pois isso determina o comportamento e as estruturas de dados que ele irá autorizar. Para minimizar impactos, você pode começar correspondendo à versão que sua integração já usa e planejar uma atualização separada depois.

Por fim, dê ao token um nome descritivo que indique sua finalidade e a versão da API (por exemplo, Reporting_v2_Read-Only) e salve com segurança as novas credenciais.

3. Teste sua integração

Antes de entrar em produção, você deve testar minuciosamente a integração atualizada em um ambiente de homologação ou desenvolvimento. Atualize temporariamente o código da sua integração nesse ambiente de teste para usar o novo token com escopo e a nova URL base da API. Execute todos os fluxos principais para verificar se leituras, criações, atualizações e exclusões de dados funcionam como esperado.

Como parte dos seus testes de segurança, tente acessar um endpoint que não esteja coberto pelos escopos do novo token. Você deve receber um 403 Forbidden erro, o que confirma que o token está restringindo o acesso corretamente. Após corrigir qualquer código com base na sua avaliação de impacto, como atualizar a lógica de requisição/resposta ou os nomes dos campos, teste novamente e itere até que todas as funções funcionem corretamente.

4. Atualize sua integração

Após o teste bem-sucedido, você estará pronto para implantar as alterações no seu ambiente de produção. Implemente todas as alterações de código e atualizações de configuração validadas na sua base de código de produção.

A etapa mais importante aqui é substituir o antigo token legado pelo novo token com escopo. Assim que o novo token estiver ativo, monitore de perto os logs da integração e do aplicativo para garantir que nenhum erro inesperado ocorra.

5. Comunique a mudança

Depois de confirmar que sua nova integração está funcionando sem problemas, é hora de revogar permanentemente ou excluir o antigo token legado não utilizado. Esta é uma etapa crucial de segurança, pois um token legado comprometido com permissões amplas representa um risco significativo.

Para encerrar o processo, atualize sua documentação interna e informe os membros relevantes da equipe sobre o novo token. Certifique-se de documentar como ele é gerenciado para evitar uso indevido e garantir uma manutenção tranquila no futuro.