Tokens e segurança

Contrato de autenticação

A API externa usa:

POST {SYSLED_URL}/api/v1/{SYSLED_TOKEN}/{metodo}

O token documentado tem 64 caracteres hexadecimais e pertence a uma empresa. Ele não é JWT nem credencial de outros canais de integração. Obtenha o host e o token com um administrador autorizado em Configurações → API Pública.

Escopo mínimo

Autorize o nome exato do método sempre que possível. Os agrupamentos amplos auditados são:

• crm.full: leads, negócios, empresas, contatos, funis, etapas e tarefas;
• catalog.full: métodos products.*;
• shop.full: somente shop.*, sem catálogo ou pedidos.

O texto literal products.* não é um wildcard reconhecido. Para o portal público, prefira os 18 escopos exatos descritos na referência.

Armazenamento

• Guarde SYSLED_TOKEN em secret manager ou variável protegida do servidor.
• Nunca coloque o token em frontend, HTML, aplicativo distribuído ou repositório.
• Não use o token em parâmetros de telemetria, traces ou mensagens de erro.
• A URL contém o segredo. Redija /api/v1/{token}/ em logs de proxy, APM, histórico, console Postman e relatórios de CI.
• Use HTTPS. Whitelist de IP e CORS são camadas complementares, não substitutos de escopo e rotação.

Exemplo de filtro de log:

export function redactSysledUrl(text) {
  return String(text).replace(/\/api\/v1\/[a-f0-9]{64}(?=\/)/gi, "/api/v1/[REDACTED]");
}

Rotação e revogação

1. Crie um token novo com os mesmos escopos mínimos, sem desativar o anterior.
2. Atualize o secret manager e reinicie/recarregue apenas os consumidores previstos.
3. Valide uma consulta segura e confira que os logs não contêm o token.
4. Revogue o token anterior no painel autorizado.
5. Confirme que o token antigo retorna erro e que o novo segue funcional.

Não existe nesta revisão um contrato público de rotação automática nem sobreposição garantida. Combine a janela com o administrador.

Incidente de exposição

Trate uma URL completa copiada para ticket, chat, analytics ou log público como vazamento do token. Remova a exposição quando possível, revogue o token, emita outro com escopo mínimo e revise acessos durante a janela. Não inclua o valor comprometido no registro do incidente.