Pular para o conteúdo principal

Gerenciamento de Chaves de API

A interface de Gerenciamento de Chaves de API fornece uma UI baseada na web para criar, monitorar e gerenciar chaves de API usadas para acesso programático à API do OmniCRM.

::: note ::: title Nota :::

Para conceitos gerais de autenticação de API e exemplos de uso, consulte concepts_api. :::

Visão Geral​

As chaves de API permitem autenticação segura e de longa duração para:

  • Integrações servidor-a-servidor
  • Scripts de automação
  • Aplicativos de terceiros
  • Tarefas agendadas e jobs cron
  • Sistemas de monitoramento externos

Ao contrário dos tokens JWT (que expiram após minutos/horas), as chaves de API permanecem válidas até serem revogadas manualmente ou até sua data de expiração.

Acessando o Gerenciamento de Chaves de API​

Navegue para:

Ou diretamente:

Permissão Necessária: MANAGE_API_KEYS (papel de administrador)

Visualização da Lista de Chaves de API​

A página principal exibe todas as chaves de API em formato de tabela:

Colunas:

  • Nome - Rótulo descritivo para a chave de API (por exemplo, "Sistema de Provisionamento", "Ferramenta de Monitoramento")
  • Criado Por - Nome de usuário da pessoa que criou a chave
  • Chave de API - A string da chave real (parcialmente mascarada por segurança)
  • Status - Ativa, Expirada ou Revogada
  • Data de Criação - Quando a chave foi gerada
  • Data de Expiração - Quando a chave expirará automaticamente
  • Ações - Botões Editar, Excluir, Regenerar

Exemplo de Exibição:

Widgets do Painel​

Na parte superior da página, estatísticas resumidas são exibidas:

  • Total de Chaves de API - Contagem de todas as chaves de API (ativas e inativas)
  • Chaves Ativas - Chaves atualmente válidas
  • Expirando em Breve - Chaves que expiram nos próximos 30 dias
  • Chaves Expiradas - Chaves que passaram da data de expiração

Criando uma Chave de API​

Passo 1: Clique em "Adicionar Chave de API"

Clique no botão + Adicionar no canto superior direito da lista de Chaves de API.

Passo 2: Preencha os Detalhes

Um formulário modal aparece solicitando:

Nome: ________________________

: (por exemplo, "Sistema de Provisionamento")

Descrição: __________________

: (Opcional - propósito desta chave)

Data de Expiração: [Selecionador de Data]

: (Opcional - deixe em branco para sem expiração)

Permissões: ☐ Visualizar Clientes ☐ Criar Clientes ☐ Visualizar Serviços ☐ Criar Serviços ☐ Provisionamento ☐ Visualizar Inventário ☑ Administrador (todas as permissões)

[Cancelar] [Gerar Chave]

Diretrizes para os Campos:

Nome (obrigatório)

  • Identificador curto e descritivo
  • Exemplos: "Sistema de Provisionamento", "Integração de Faturamento", "Monitoramento"
  • Usado em logs de auditoria e exibido na lista

Descrição (opcional)

  • Explicação mais detalhada
  • Exemplos: "Usado pelo servidor de provisionamento Ansible", "Sincronização de faturamento de terceiros"
  • Ajuda futuros administradores a entender o propósito da chave

Data de Expiração (opcional)

  • Se em branco: A chave nunca expira (não recomendado)
  • Se definida: A chave se torna automaticamente inválida após esta data
  • Recomendado: Definir expiração por segurança (90 dias a 1 ano)

Permissões

  • Selecione permissões específicas ou marque "Administrador" para acesso total
  • Segue o mesmo modelo de permissão baseado em papéis que contas de usuário
  • Melhor Prática: Atribua as permissões mínimas necessárias

Passo 3: Gerar e Copiar a Chave

Após clicar em "Gerar Chave", o sistema exibe a nova chave de API criada:

⚠️ Copie esta chave agora - ela não será exibida novamente!

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

[Copiar para a Área de Transferência]

[Fechar]

::: warning ::: title Aviso :::

Salve a chave de API imediatamente!

Uma vez que você feche este diálogo, a chave completa não poderá ser recuperada novamente. Você só verá uma versão mascarada (sk_live_...XYZ) na visualização da lista.

Se você perder a chave, deve regenerá-la, o que invalida a chave antiga e pode quebrar integrações existentes. :::

Passo 4: Configure Seu Aplicativo

Use a chave de API nas solicitações do seu aplicativo:

curl -X GET "https://yourcrm.com/crm/customers" \
  -H "X-API-KEY: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Ou em variáveis de ambiente:

export CRM_API_KEY="sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"

Gerenciando Chaves Existentes​

Visualizando Detalhes da Chave​

Clique em qualquer nome de chave de API para ver os detalhes completos:

  • Nome completo da chave e descrição
  • Timestamp de criação
  • Nome de usuário do criador
  • Permissões associadas
  • Estatísticas de uso (se implementadas)
  • Logs de acesso recentes

Regenerando uma Chave de API​

Se uma chave de API estiver comprometida ou perdida, regenere-a:

  1. Clique nos ⋮ (três pontos) na coluna Ações
  2. Selecione "Regenerar Chave"
  3. Confirme a ação

::: warning ::: title Aviso :::

Regenerar invalida a chave antiga imediatamente.

Qualquer aplicativo usando a chave antiga deixará de funcionar. Atualize todas as integrações com a nova chave antes de regenerar. :::

O que Acontece:

  • A chave antiga é revogada
  • Uma nova chave com as mesmas permissões é gerada
  • A nova chave é exibida (copie-a imediatamente)
  • Nome, descrição e permissões permanecem inalterados

Revogando (Excluindo) uma Chave de API​

Para remover permanentemente uma chave de API:

  1. Clique nos ⋮ (três pontos) na coluna Ações
  2. Selecione "Excluir"
  3. Confirme a exclusão

O que Acontece:

  • A chave é imediatamente revogada
  • Todas as solicitações usando esta chave retornam 401 Unauthorized
  • A chave é removida do banco de dados
  • Não pode ser desfeito - a chave não pode ser recuperada

Quando Revogar:

  • A integração não é mais necessária
  • A chave foi comprometida
  • O sistema que usa a chave foi desativado
  • Substituindo por uma nova chave com permissões diferentes

Editando Detalhes da Chave de API​

Para modificar os detalhes de uma chave de API:

  1. Clique nos ⋮ (três pontos) na coluna Ações
  2. Selecione "Editar"
  3. Atualize nome, descrição, expiração ou permissões
  4. Clique em "Salvar Alterações"

Campos Editáveis:

  • Nome
  • Descrição
  • Data de expiração
  • Permissões

Não Editáveis:

  • O valor da chave em si (use Regenerar para alterar)
  • Data de criação
  • Criado por usuário

Status da Chave de API​

As chaves de API podem ter vários status:

Ativa

  • A chave é válida e pode ser usada
  • Dentro da data de expiração (ou sem expiração definida)
  • Não foi revogada manualmente
  • Exibida com um distintivo verde

Expirando em Breve

  • Ativa, mas expirará nos próximos 30 dias
  • Exibida com um distintivo laranja/aviso
  • Considere rotacionar antes da expiração

Expirada

  • Passou da data de expiração
  • Não aceita mais autenticação
  • Exibida com um distintivo vermelho
  • Pode ser excluída ou a expiração estendida

Revogada

  • Excluída/desativada manualmente
  • Permanentemente inválida
  • Não é mais exibida na lista ativa

Filtrando e Pesquisando​

A lista de Chaves de API suporta:

Pesquisa:

Pesquise por nome, descrição ou chave parcial:

Filtrar por Status:

Filtro suspenso para mostrar:

  • Todas as Chaves
  • Apenas Ativas
  • Expirando em Breve (próximos 30 dias)
  • Expiradas

Ordenar:

Clique nos cabeçalhos das colunas para ordenar por:

  • Nome
  • Data de Criação
  • Data de Expiração
  • Criado Por

Melhores Práticas de Segurança​

Geração de Chaves de API​

  • Comprimento: As chaves devem ter pelo menos 32 caracteres (o sistema impõe isso)
  • Aleatoriedade: Geradas usando geradores de números aleatórios criptograficamente seguros
  • Formato: Tipicamente prefixadas (por exemplo, sk_live_) para identificação

Armazenamento de Chaves de API​

No CRM:

  • As chaves são hashadas antes do armazenamento (como senhas)
  • A chave completa é mostrada apenas uma vez durante a criação
  • O banco de dados armazena o hash para verificação
  • Mesmo administradores não podem recuperar a chave completa depois

No Seu Aplicativo:

  • Armazene em variáveis de ambiente, não no código
  • Use sistemas de gerenciamento de segredos (AWS Secrets Manager, HashiCorp Vault)
  • Nunca comite chaves no controle de versão
  • Rotacione chaves periodicamente (90-365 dias)

Gerenciamento de Permissões​

  • Princípio do Menor Privilégio - Conceda apenas as permissões necessárias
  • Evite criar chaves de administrador, a menos que absolutamente necessário
  • Use chaves separadas para diferentes sistemas/purposes
  • Revise permissões regularmente

Monitoramento e Auditoria​

  • Monitore o uso da chave de API por meio de logs de atividade
  • Configure alertas para padrões de acesso incomuns
  • Revise timestamps de "último uso" regularmente
  • Remova chaves não utilizadas

Rotação de Chaves​

Estabeleça uma política de rotação de chaves:

  1. Crie uma nova chave com as mesmas permissões
  2. Atualize os aplicativos para usar a nova chave
  3. Monitore para garantir que a chave antiga não seja mais usada
  4. Revogue a chave antiga após o período de carência

Solução de Problemas​

"401 Unauthorized" ao usar a chave de API

  • Causa: Chave inválida, expirada ou incorreta
  • Correção:
    • Verifique se a chave foi copiada corretamente (sem espaços extras)
    • Verifique o status da chave (Ativa vs. Expirada)
    • Confirme se a chave tem as permissões necessárias
    • Certifique-se de usar o cabeçalho X-API-KEY (não Authorization)

"Chave de API não encontrada" após a criação

  • Causa: A chave pode ter sido criada, mas não armazenada corretamente
  • Correção:
    • Verifique a lista de chaves de API para a nova entrada
    • Se estiver faltando, crie uma nova chave
    • Relate o problema ao administrador

Chave de API expirando em breve

  • Causa: Data de expiração se aproximando (dentro de 30 dias)
  • Correção:
    • Crie uma nova chave com expiração estendida
    • Atualize os aplicativos para usar a nova chave
    • Revogue a chave antiga após a migração

Não é possível excluir a chave de API

  • Causa: Pode estar protegida ou em uso
  • Correção:
    • Certifique-se de que você tem permissões de administrador
    • Verifique se a chave está bloqueada/protegida
    • Entre em contato com o administrador se o problema persistir

Endpoints da API (para Gerenciamento Programático)​

As chaves de API também podem ser gerenciadas via API (requer permissões de administrador):

Listar Chaves de API

GET /crm/api-keys
Authorization: Bearer <admin-token>

Criar Chave de API

POST /crm/api-keys
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nova Integração",
  "description": "Sincronização de faturamento de terceiros",
  "expiry_date": "2026-01-10",
  "permissions": ["view_customer", "view_service"]
}

Resposta:

{
  "api_key_id": 123,
  "name": "Nova Integração",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created": "2025-01-10T10:00:00Z",
  "expiry_date": "2026-01-10T23:59:59Z"
}

Revogar Chave de API

DELETE /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>

Atualizar Chave de API

PATCH /crm/api-keys/{api_key_id}
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Nome Atualizado",
  "expiry_date": "2026-12-31"
}

Casos de Uso Comuns​

Caso de Uso 1: Integração do Sistema de Provisionamento

Crie uma chave de API para seu servidor de provisionamento Ansible:

  1. Navegue para Chaves de API → Adicionar
  2. Nome: "Servidor de Provisionamento Ansible"
  3. Descrição: "Usado pela automação de provisionamento"
  4. Permissões: Provisionamento, Visualizar/Criar Serviços, Visualizar/Atualizar Inventário
  5. Expiração: 1 ano
  6. Copie a chave e adicione ao crm_config.yaml do Ansible

Caso de Uso 2: Integração de Faturamento de Terceiros

Crie uma chave somente leitura para exportação de faturamento:

  1. Nome: "Sincronização de Faturamento - QuickBooks"
  2. Permissões: Visualizar Clientes, Visualizar Transações, Visualizar Faturas
  3. Expiração: 90 dias (rotacione trimestralmente)
  4. Use no script de exportação agendada

Caso de Uso 3: Monitoramento e Alertas

Crie uma chave para coleta de métricas do Prometheus/Grafana:

  1. Nome: "Monitoramento - Grafana"
  2. Permissões: Visualizar Serviços, Visualizar Provisionamento
  3. Expiração: Nunca (monitoramento precisa de acesso contínuo)
  4. Configure na fonte de dados do Grafana

Caso de Uso 4: API do Portal do Cliente

Crie uma chave para o portal de autoatendimento do cliente:

  1. Nome: "Backend do Portal do Cliente"
  2. Permissões: Visualizar Próprio Cliente, Visualizar Próprios Serviços, Criar Pagamentos
  3. Expiração: 180 dias
  4. Use nas chamadas da API do backend do portal

Documentação Relacionada​

  • concepts_api - Conceitos e exemplos de autenticação de API
  • rbac - Controle de acesso baseado em papéis e permissões
  • 2fa - Autenticação de dois fatores para segurança adicional