Interaflow

Guias

Chaves de API

Cada chave tem prefixo visível e hash armazenado. Use no header X-API-Key ou Authorization: Bearer ik_... Escopo limita o que a chave pode fazer.

Atualizado em

O que são

Chaves de API são credenciais usadas por integradores externos para autenticar requisições programáticas ao Interaflow — leitura de Conversas, criação de contatos, busca de gravações, qualquer endpoint público da API. Cada chave pertence a um tenant, tem um nome amigável, escopo de operações permitidas e — opcionalmente — data de expiração e limite de chamadas por minuto.

A chave é gerada uma única vez e exibida na criação. O backend armazena apenas o hash SHA-256 — depois de fechar a tela de criação, ninguém (nem o admin) consegue recuperar o valor original. Se perdeu, gere outra.

Formato da chave

Cada chave tem o formato ik_<sufixo aleatório>. O prefixo ik_ ajuda a identificar visualmente a credencial em logs e no help-desk. Exemplo:

ik_a3Bf9xQp7n4mVwL2yJzR8tHsK1cE6dGu

Após salvar, a UI mostra apenas o prefixo curto (ex.: ik_a3Bf9x...) — o resto é hash. Inclua o valor inteiro no gerenciador de segredos do seu sistema antes de fechar a tela de criação.

Como autenticar

A API aceita a chave em dois formatos equivalentes:

Header X-API-Key

curl https://app.interaflow.com.br/api/v1/conversations \
  -H "X-API-Key: ik_a3Bf9xQp7n4mVwL2yJzR8tHsK1cE6dGu"

Header Authorization: Bearer

curl https://app.interaflow.com.br/api/v1/conversations \
  -H "Authorization: Bearer ik_a3Bf9xQp7n4mVwL2yJzR8tHsK1cE6dGu"

Use o que for mais natural no seu cliente HTTP. Os dois funcionam identicamente.

Cadastrar uma chave nova

  1. Configurações → Chaves de API → Nova chave.
  2. Nome — descritivo, indicando o consumidor (ex.: “BI Looker Studio”, “Sync HubSpot — produção”, “Importação noturna ETL”). Aparece na lista para auditoria.
  3. Descrição — opcional, contexto adicional.
  4. Escopos — selecione apenas o que a chave precisa fazer (detalhe na próxima seção).
  5. Expiração — opcional. Se você sabe que a chave é temporária (job de migração, integração de teste), aproveite e já defina a data.
  6. Rate limit — opcional. Se vazio, usa o padrão global do tenant.
  7. Salvar. A UI exibe uma única vez o valor completo. Copie e guarde no gerenciador de segredos. Após fechar, só restará o prefixo na lista.

Escopos

O escopo limita o conjunto de operações que a chave pode realizar — equivalente a “permissão” no jargão clássico de API. O modelo é uma lista JSON de pares recurso:ação, similar a:

["conversations:read", "campaigns:read", "campaigns:write"]

Padrões úteis:

  • Leitura apenas — *:read para chave que alimenta dashboards externos / BI.
  • Escrita restrita — contacts:write, mailings:write para chave que importa dados.
  • Operação específica — escopo cirúrgico para integrações com responsabilidade limitada (ex.: chave que só pode marcar Conversa como “encerrada”).

A lista exata de escopos disponíveis aparece no formulário de criação — selecione conforme a documentação da API que você vai consumir.

Rate limit

Cada chave tem um limite de chamadas por minuto (rate limit RPM). Quando vazio na chave, vale o padrão global do tenant. Quando preenchido, sobrescreve o default para aquela chave específica.

Use rate limit por chave para:

  • Proteger a plataforma de consumidor desconfigurado em loop.
  • Garantir SLA para uma chave crítica em períodos de contenção.
  • Distribuir capacidade entre múltiplos consumidores que competem por API.

Quando o limite é atingido, o backend devolve 429 Too Many Requests — o cliente deve respeitar o Retry-After retornado.

Status e expiração

  • is_active — chave ativa entrega autenticação válida. Desativar bloqueia uso imediatamente sem precisar excluir.
  • expires_at — data/hora de expiração. Após o prazo, o backend rejeita a chave automaticamente. Útil para chaves temporárias (migração, integração piloto).
  • last_used_at / last_used_ip — registros de auditoria populados a cada uso. Permite identificar chaves esquecidas (sem uso há semanas) ou origem inesperada.

Rotação

A rotação é manual — não há rotação automática agendada por política. O caminho recomendado:

  1. Crie a chave nova com o mesmo nome + sufixo “-v2” (ou convenção semelhante) e o mesmo escopo.
  2. Atualize o consumidor para usar a chave nova.
  3. Confirme o uso olhando last_used_at da chave nova.
  4. Desative a chave antiga (is_active = false). Mantenha por alguns dias para rollback se algo quebrar.
  5. Exclua a chave antiga (soft delete) depois de confirmada a estabilidade.

Cadência recomendada: rotação trimestral para chaves críticas, imediata para chaves potencialmente comprometidas.

Auditoria

Por chave, você sabe:

  • Quem criou (created_by_user_id).
  • Quando foi criada (created_at).
  • Último uso (last_used_at) e de qual IP (last_used_ip).
  • Status atual (ativa / desativada / expirada).

Use essa informação para:

  • Identificar chaves que ninguém mais usa (candidatas a remoção).
  • Detectar uso de IP inesperado (vetor de comprometimento).
  • Auditoria de conformidade (“essa chave foi criada por quem, quando, e está em uso por quem hoje?”).

Boas práticas

  • Uma chave por consumidor. Não compartilhe entre serviços diferentes — perde rastreabilidade e dificulta revogação pontual.
  • Escopo mínimo. Pergunta padrão ao criar: “qual é o menor conjunto de operações que esse consumidor precisa?”.
  • Expire chaves temporárias. Se sabe que a chave vive 30 dias (migração, piloto), já preencha expires_at — esquecimento é a causa #1 de credencial órfã.
  • Guarde no gerenciador de segredos. Não em variável de ambiente versionada, não em planilha, não em mensagem de Slack.
  • Audite mensalmente. Lista chaves sem uso há 30 dias — candidatas a desativar/excluir.
  • Não exponha chave em frontend público. Chave de API é credencial de servidor; cliente JavaScript não tem como proteger o segredo.

Limites conhecidos

  • Sem rotação automática agendada — rotação é manual.
  • Sem MFA na criação da chave — protege quem criou pelo SSO/ senha do User criador.
  • Hash SHA-256 sem salt por design — chave aleatória de 32+ caracteres já garante entropia suficiente.
  • Sem revogação imediata em todos os caches — a invalidação pode levar segundos para propagar em ambientes com cache agressivo.

Erros comuns

  • Tentar recuperar chave perdida. Não dá. Hash não é reversível. Crie uma nova e atualize o consumidor.
  • Compartilhar chave entre múltiplos serviços. Se um vaza, você precisa rotacionar para todos.
  • Esquecer de desativar chave de funcionário que saiu. Combine desativação no offboarding.
  • Usar chave em frontend. Qualquer um vê pelo DevTools. Use chave só em servidor.
  • Definir rate limit muito baixo sem testar — consumidor legítimo começa a tomar 429 e quebra.

Ver também