Autenticação e permissões

A API recebe uma chave opaca no cabeçalho Bearer:

Authorization: Bearer <COTEJAR_API_KEY>

A chave não é JWT, não contém permissões que o integrador possa decodificar e não é um token do MCP. Ela é emitida no contexto de uma empresa e nunca permite trocar de empresa por um campo no corpo ou na URL.

Permissões

Escopo	Permite
`conta:ler`	Ler o contexto da chave, a empresa e as capacidades.
`catalogo:ler`	Ler estabelecimentos, catálogos, produtos, ingestões e resultados.
`catalogo:escrever`	Criar ou editar produtos, vínculos e preparar ingestões.
`catalogo:aplicar`	Aplicar uma prévia de ingestão já validada.
`catalogo:gerenciar`	Criar, editar e excluir catálogos após conferir o impacto.
`estabelecimento:gerenciar`	Criar, editar e arquivar estabelecimentos; solicitar correção de CNPJ.
`vigilancia:gerenciar`	Alterar a seleção da vigilância.
`analise:executar`	Solicitar uma análise completa da empresa.
`webhook:gerenciar`	Configurar o destino e consultar, testar ou reenviar eventos.

As permissões são escolhidas na emissão. Uma chave existente não recebe novos escopos automaticamente, e a rotação conserva seus escopos. Plano, assinatura, franquia e capacidade são verificados separadamente em cada operação.

Use uma chave com o menor conjunto necessário. Uma integração que só recebe webhooks pode usar webhook:gerenciar; ela não precisa ler os produtos.

Guardar e identificar

Guarde a chave em um gerenciador de segredos do servidor.
Registre empresa, finalidade, validade, responsável e o ID ou prefixo não secreto.
Não coloque a chave no navegador, URL, repositório, imagem, log, captura de tela ou ticket.
Não use a chave Bearer como Idempotency-Key.

Expiração, rotação e revogação

A expiração encerra o uso no instante informado. Uma rotação revoga a chave anterior imediatamente e emite outra; não há sobreposição automática. Para uma troca planejada, crie outra credencial, valide-a no integrador e só então revogue a antiga.

Revogar uma chave impede novas operações por ela, mas não apaga o catálogo ou os resultados. Um trabalho assíncrono revalida sua autorização durante o processamento e pode terminar com falha explícita se a credencial responsável perder o acesso.