Autenticação e permissões

Toda chamada leva a credencial no cabeçalho Authorization:

Authorization: Bearer ctj_api_<id>.<segredo>

A chave é opaca: não é JWT, não carrega permissões legíveis e não serve para o MCP. Ela é emitida dentro de uma empresa e nunca troca de empresa por um campo do corpo ou da URL. Para descobrir o que uma chave autoriza, consulte GET /v1/conta.

Permissões

Cada credencial recebe as permissões marcadas no painel. A coluna No painel mostra o rótulo exato do formulário; Inclui mostra o que é marcado junto.

Escopo	No painel	Inclui	Permite
`conta:ler`	Consultar conta	—	Ler o contexto da chave, a empresa e as capacidades.
`catalogo:ler`	Consultar catálogo	—	Ler estabelecimentos, catálogos, produtos, ingestões e resultados.
`catalogo:escrever`	Enviar produtos	`catalogo:ler`	Criar e editar produtos e vínculos; iniciar ingestões, enviar e validar lotes.
`catalogo:aplicar`	Aplicar lotes	`catalogo:escrever`	Aplicar a prévia validada de uma ingestão.
`catalogo:gerenciar`	Gerenciar catálogos	`catalogo:ler`	Criar, editar e excluir catálogos depois de conferir o impacto.
`estabelecimento:gerenciar`	Gerenciar estabelecimentos	`catalogo:ler`	Criar, editar e arquivar estabelecimentos; pedir correção de CNPJ.
`vigilancia:gerenciar`	Gerenciar vigilância	`catalogo:ler`	Alterar a seleção de produtos vigiados.
`analise:executar`	Executar análises	`catalogo:ler`	Solicitar uma análise completa da empresa.
`webhook:gerenciar`	Gerenciar webhooks	—	Configurar o destino e consultar, testar ou reenviar eventos.

Cada rota dos guias mostra a permissão que exige ao lado do caminho. Plano, franquia e capacidade são conferidos à parte, em cada operação: ter analise:executar não garante franquia disponível.

Conjuntos comuns

Integração	Permissões
ERP que sincroniza o catálogo e pede análises	`conta:ler`, `catalogo:aplicar`, `analise:executar`, `webhook:gerenciar` (as dependências entram sozinhas)
Painel interno que só lê resultados	`conta:ler`, `catalogo:ler`
Receptor que só administra webhooks	`webhook:gerenciar`

Use o menor conjunto que resolve o problema. Uma credencial vazada com catalogo:ler expõe o catálogo; com catalogo:aplicar, também permite alterá-lo.

Ciclo de vida

Validade: 90 dias a partir da emissão. Depois disso a chave recebe 401.
Rotacionar: emite uma chave nova com as mesmas permissões e revoga a anterior no mesmo instante. Não há período de convivência.
Revogar: encerra a chave imediatamente. Catálogo e resultados continuam intactos.

Um trabalho assíncrono revalida a autorização durante o processamento. Se a credencial que pediu uma aplicação ou análise for revogada no meio do caminho, o trabalho termina com falha explícita, nunca em silêncio.

Cartão Credencial da API com duas credenciais: ERP — integração completa, com as nove permissões, e ERP principal, com seis. Cada uma mostra validade até 11/01/2027 e os botões Rotacionar e Revogar. — Cada credencial mostra o prefixo, as permissões, a validade e o último uso. O segredo completo não volta a aparecer.

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

Como Rotacionar derruba a chave antiga na hora, a troca planejada usa duas credenciais:

Crie uma credencial nova com as mesmas permissões, com o nome do sistema e a data, como ERP principal 2027-01.
Publique a chave nova no gerenciador de segredos do servidor e reinicie a integração.
Confirme com GET /v1/conta que o credencial_id mudou e que as chamadas seguem com sucesso.
Revogue a credencial antiga no painel.

Use Rotacionar só quando a chave pode ter vazado: a interrupção é o comportamento desejado.

Guardar e identificar

Guarde a chave em um gerenciador de segredos do servidor.
Registre empresa, finalidade, validade, responsável e o prefixo não secreto.
Nunca coloque a chave no navegador, em URL, repositório, imagem, log, captura de tela ou chamado de suporte.
Não use a chave como Idempotency-Key.
Envie a chave somente para https://api.cotejar.com.br. Não siga redirecionamentos com o cabeçalho Authorization.