Segredo cifrado. A validação usa só uma assinatura (hash com segredo do servidor) da chave; a chave em si fica guardada cifrada, para o dono copiá-la de novo. Ninguém mais, nem o administrador, consegue vê-la. As telas mostram apenas o prefixo.
Permissões do usuário. A chave herda os menus, funis e restrições do dono. A empresa vem sempre da chave, nunca de um parâmetro da requisição; um id de empresa diferente na URL responde 403.
Lista fechada de rotas. Só as 165 rotas da Referência de rotas aceitam a chave. Sessão, administração, MCP, gestão de chaves, compra de créditos e as demais rotas internas respondem 403 error_api_key_forbidden_route.
Limites. 300 requisições por minuto por chave e 1.500 por empresa. Veja Limite de requisições.
Revogação imediata. Revogar a chave, gerar uma nova, desativar o usuário, retirar o menu do perfil ou inativar a empresa vale na requisição seguinte.
Validade e aviso. Chaves com prazo vencem sozinhas, e o dono recebe e-mail 7 dias antes.
Registro de uso. Toda requisição, aceita ou negada, entra no log com método, rota, status, duração e IP, e a chave guarda o último uso e o IP. O log fica 90 dias. A aba Uso da tela Integração API mostra esse registro por chave e por rota.
Trate a chave como senha. Guarde em variável de ambiente ou cofre de segredos. Nunca em repositório, planilha, e-mail ou chat.
Nunca no frontend. Não coloque a chave em JavaScript de site, aplicativo móvel ou qualquer código que chegue ao navegador do usuário final. Para formulários de site, chame a API a partir do seu servidor. Quem tiver a chave faz tudo o que o dono faz.
Um usuário dedicado por integração. Crie um usuário só para o sistema externo, com um perfil mínimo. Veja Permissões.
Prefira uma validade. Use Sem validade só em integrações de uso contínuo e revise essas chaves periodicamente; elas não recebem aviso de vencimento.
Rotacione. Gere uma chave nova de tempos em tempos e troque no sistema integrado. A anterior é revogada sozinha.
Revogue no desligamento. Quando alguém sai da empresa, o administrador revoga a chave dele em Integração API › Chaves e desativa o usuário.
Acompanhe o uso. Erros em sequência na aba Uso costumam ser chave vencida ou rota fora do catálogo; chamadas de um IP inesperado merecem revogação imediata.
Respeite os limites. Trate 429 com espera e repetição; não dispare em paralelo além do necessário.