Guias
Chaves de API e autenticação no Interaflow
Credenciais de servidor, permissões, limites e troca de chave vinculada a usuário por JWT.
Atualizado em
Criar uma chave
Em Configurações → Chaves de API, crie uma chave com nome que identifique o consumidor, como “BI de atendimento”. Escolha os escopos, o limite de chamadas por minuto e, quando necessário, a expiração.
A credencial completa começa com ik_ e aparece somente na criação. Guarde-a no gerenciador de segredos do seu servidor. Depois, o painel mostra o prefixo, o estado e os dados de uso; a chave completa não pode ser recuperada.
A API administrativa de criação aceita expires_in_days de 1 a 365 e rate_limit_rpm de 1 a 10.000. O padrão de criação é 60 requisições por minuto; o limite efetivo depende da chave salva e da configuração do ambiente.
Autenticar uma consulta
Para a API de Integração, use um dos dois headers equivalentes. IF_BASE_URL é a origem HTTPS do seu ambiente, sem barra final; IF_API_KEY é a chave completa.
curl "$IF_BASE_URL/api/v1/integracao/v1/listas" \
-H "X-API-Key: $IF_API_KEY"curl "$IF_BASE_URL/api/v1/integracao/v1/listas" \
-H "Authorization: Bearer $IF_API_KEY"A consulta de listas requer uma chave válida. Para sessões, chamadas, gravações e cadastros, adicione os escopos exigidos na referência da API.
Escopos
Os nomes são explícitos e validados na criação da chave. Não use curingas como *:read ou admin:*.
| Família | Valores aceitos |
|---|---|
| Administração | admin:read, admin:write |
| Chamadas | calls:read, calls:write |
| Campanhas | campaigns:read, campaigns:write |
| Contatos | contacts:read, contacts:write |
| Relatórios e gravações | reports:read, recordings:read |
| Canais | channels:read, channels:write |
| Conversas | conversations:read, conversations:write |
| Webhooks | webhooks:manage |
| URA e cadastros | ivr:read, catalog:read |
| Dados pessoais adicionais | pii:read |
A existência de um escopo não significa que todos os endpoints de uma família aceitem chave de API ou apliquem esse escopo. O contrato da rota determina a autenticação e as permissões exigidas. O endpoint administrativo GET /api/v1/api-keys/scopes lista os escopos disponíveis na versão do ambiente.
Para uma extração de URA e cadastros, por exemplo:
["ivr:read", "catalog:read"]Conceda pii:read apenas quando o consumidor precisar dos valores adicionais de dados capturados e da transcrição de URA sem a máscara de CPF. Ele não substitui o escopo de leitura do recurso.
Chave direta ou JWT
| Contrato | Autenticação |
|---|---|
/api/v1/integracao/v1/* de dados | Chave direta e escopos por rota; JWT de usuário não é aceito |
Callback /api/v1/conversations/{conversation_id}/agent-callback | Chave direta ou JWT; chave vinculada a usuário não é obrigatória |
Consulta GET /api/v1/agent-deliveries | Chave direta ou JWT |
Teste POST /api/v1/agent-deliveries/test | JWT de usuário |
| Endpoints internos que exigem usuário, como envio de mensagem pelo atendente | JWT e permissões do usuário |
Callback e consulta de entregas verificam a organização da chave, sem exigir escopo adicional por recurso no contrato atual. Conceder poucos escopos à chave não restringe essas duas rotas a uma única conversa.
Trocar uma chave vinculada a usuário por JWT
Quando a integração precisa de endpoints que exigem usuário, um administrador pode criar a chave com acts_as_user_id apontando para um usuário da mesma organização. Esse usuário deve estar ativo e ter as permissões adequadas.
curl -X POST "$IF_BASE_URL/api/v1/auth/api-key/exchange" \
-H "X-API-Key: $IF_API_KEY"A resposta inclui access_token. Use esse JWT em Authorization: Bearer nos endpoints compatíveis. O token tem duração de uma hora no contrato atual. Seu acesso segue as permissões do usuário vinculado; os escopos da chave não substituem esse controle.
Uma chave sem vínculo retorna 400 api_key_not_bound_to_user. Usuário inativo ou vínculo inválido retorna 403. Esse exchange não é necessário para consultar a API de Integração nem para o callback do Controle Externo.
Limites e erros
Ao receber 429, respeite Retry-After, em segundos. Evite novas tentativas em loop. Para 401, confira se a chave está ativa e não expirou. Para 403 missing_scope:..., peça ao administrador o escopo específico exigido pela rota.
Rotação e acompanhamento
Crie uma chave por consumidor. Para rotacionar, crie uma nova, atualize a integração, valide o acesso e desative a anterior. Não grave chaves em código público, aplicações de navegador, planilhas ou logs.
O painel permite acompanhar prefixo, criação, último uso, IP e estado da chave. Revise acessos que deixaram de ser necessários. A rotação é manual.