Migrar 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 nas APIs da impact.com, é hora de migrar para tokens com escopo.

Tokens legados concedem acesso amplo 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 gerenciável. Leia mais sobre Melhores práticas para tokens com escopo.

Etapas de 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 migrar para uma versão mais recente da API.

Comece listando cada integração e registrando sua função, os endpoints específicos que acessa, os tipos de ações que executa (leitura, escrita ou ambos) e quem é o proprietário ou responsável pela manutenção da integração.

Preste atenção especial a quaisquer mudanças incompatíveis entre versões da API. Você deve:

• Revisar seus payloads de requisição, 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.

• Examinar a estrutura dos payloads de resposta, pois campos podem ser renomeados, removidos ou aninhados de forma diferente, o que exigirá atualizações na lógica do seu aplicativo para ler as respostas da API.

2. Gere um novo token com escopo

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

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

Selecione a versão de API alvo ao gerar o token, pois isso dita o comportamento e as estruturas de dados que ele autorizará. Para minimizar interrupções, você pode começar correspondendo à versão que sua integração já usa e planejar uma atualização separada posteriormente.

Por fim, dê ao token um nome descritivo que indique seu propósito e a versão da API (por exemplo, Reporting_v2_Read-Only) e salve as novas credenciais de forma segura.

3. Teste sua integração

Antes de entrar em produção, você deve testar minuciosamente a integração atualizada em um ambiente de staging 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 de trabalho principais para verificar se leituras, criações, atualizações e exclusões de dados funcionam conforme esperado.

Como parte dos seus testes de segurança, tente acessar um endpoint que não seja 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 nomes de campos, teste novamente e itere até que todas as funções funcionem corretamente.

4. Atualize sua integração

Após testes bem-sucedidos, você está pronto para implantar as alterações em seu ambiente de produção. Implemente todas as alterações de código validadas e atualizações de configuração no seu codebase de produção.

A etapa mais importante aqui é substituir o token legado antigo pelo novo token com escopo. Uma vez que o novo token esteja ativo, monitore de perto os logs da integração e da aplicação para garantir que não ocorram erros inesperados.

5. Comunique a mudança

Depois de confirmar que sua nova integração está funcionando sem problemas, é hora de revogar ou excluir permanentemente o token legado antigo e não utilizado. Este é um passo 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.