Pular para o conteúdo
gensAPI

Autenticação

A API Pública V1 usa API Keys vinculadas a uma clínica, no esquema HTTP Bearer. Cada chave pertence a uma única clínica e não permite selecionar outra. Crie chaves separadas por integração e conceda apenas as permissões necessárias.

Onde a chave é aceita#

Somente no cabeçalho Authorization, com o prefixo Bearer :

http
Authorization: Bearer ck_live_EXEMPLO_REDACTED_EXEMPLO_REDACTED_EXEMPLO_REDACTED

A chave nunca deve ser enviada para:

  • navegador, aplicativo móvel distribuído ou página web;
  • query string, path, body ou header customizado;
  • logs, analytics, ferramenta de rastreamento, screenshot ou repositório;
  • localStorage, sessionStorage, cookies ou cache compartilhado.

A integração é exclusivamente server-to-server, a partir de um backend controlado pela clínica.

Formato da chave#

O valor segue o regex ^ck_live_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$:

  • prefixo fixo ck_live_;
  • 32 caracteres hexadecimais que identificam a credencial;
  • sufixo de 43 caracteres em base64url gerado a partir de 32 bytes aleatórios (crypto.getRandomValues).

A plataforma não armazena a chave em texto aberto. Ela conserva somente uma representação irreversível para validação, o prefixo de exibição (24 caracteres), os scopes, as datas de criação/expiração/revogação e o último uso. A chave completa aparece uma única vez, na resposta de criação ou rotação.

Criar uma chave#

A criação é feita pelo painel da clínica em Configurações → API. Somente o perfil clinica com status ativo pode administrar chaves; o perfil admin da plataforma e o perfil usuario não recebem impersonação na V1.

Limites por clínica:

  • no máximo 5 chaves ativas simultâneas;
  • validade padrão de 90 dias, com opções de 30, 90, 180 dias, personalizado (1 a 365) ou sem expiração;
  • cada chave precisa de pelo menos 1 scope, no máximo 26;
  • contacts:delete e followups:execute são de alto risco, ficam fora dos presets e exigem confirmação extra na interface.
  • returns:execute também exige confirmação extra porque pode iniciar e concluir execuções automáticas de retornos.
  • chaves sem expiração devem ser revogadas manualmente quando a integração deixar de ser usada.

Quando a criação é concluída, o painel mostra a chave completa uma única vez. O botão Fechar só habilita após marcar a confirmação de que a chave foi salva em local seguro (secret manager, cofre, variável de ambiente protegida).

Rotacionar e revogar#

Rotacionar no painel:

  1. gera uma nova chave com os mesmos scopes e a validade escolhida;
  2. revoga a anterior na mesma transação;
  3. exibe a nova chave uma única vez;
  4. a partir desse instante, a chave antiga retorna 401 revoked_api_key.

Rotação é imediata e deve ser usada em incidente. Para troca sem interrupção de serviço:

  1. crie uma segunda chave ativa;
  2. atualize a integração e valide;
  3. só então revogue a antiga.

Revogar interrompe o uso da chave em novas requisições. Não desfaz ações que já foram concluídas.

Guardar a chave#

Recomendado:

  • variável de ambiente protegida no servidor da clínica (nunca no repositório);
  • secret manager (Doppler, AWS Secrets Manager, Google Secret Manager, Azure Key Vault, 1Password, Bitwarden);
  • arquivo de ambiente ignorado pelo Git e restrito ao usuário do serviço (permissão 0600 em Linux; acesso equivalente no Windows).

Perder a chave#

Se o painel foi fechado sem copiar, não há recuperação: a chave completa não pode ser reconstruída. Revogue a metadata criada e gere outra.

Se houve suspeita de vazamento, revogue imediatamente pelo painel e crie uma nova.

Qual permissão escolher?#

  • Consultar contatos e vendas: contacts:read.
  • Registrar venda: contacts:write; acrescente contacts:read para consultar o contato e sua versão antes.
  • Mover um contato no funil: kanban:write; acrescente permissões de leitura dos contatos e etapas que precisar consultar.
  • Gerar rascunhos de retornos: returns:read e returns:execute. Essa permissão pode revelar contexto com mensagens; confira Retornos.
  • Ver a lista de ferramentas MCP não significa ter permissão para executá-las.

Não existe edição de scopes de uma chave já criada neste fluxo. Para mudar permissões, crie uma substituta, teste a integração e revogue a antiga.

Gens CRM · documentação da API V1 · OpenAPI · Índice para agentes · Abrir o CRM

Teste no seu terminal

GET/v1/accountaccount:read
curl
curl -sS -X GET "https://api.crm.agenciagens.com.br/v1/account" \
  -H "Authorization: Bearer ${GENS_CLINIC_API_KEY}"
powershell
$headers = @{ Authorization = "Bearer $env:GENS_CLINIC_API_KEY" }

Invoke-RestMethod -Method GET -Uri "https://api.crm.agenciagens.com.br/v1/account" -Headers $headers
javascript
// Execute somente no servidor; configure os segredos no ambiente protegido.
if (!process.env.GENS_CLINIC_API_KEY) throw new Error("Configure a API Key no servidor.");
const response = await fetch(
  "https://api.crm.agenciagens.com.br/v1/account",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.GENS_CLINIC_API_KEY}`,
    },
  },
);

if (!response.ok) throw new Error(`HTTP ${response.status}; request_id=${response.headers.get("X-Request-Id") ?? "indisponível"}`);
const result = await response.json();
// Processe result sem registrar dados pessoais em logs.

Copie, cole no seu servidor e exporte GENS_CLINIC_API_KEY antes. A chave nunca vem para o navegador — esta página não executa chamadas autenticadas.