São 215 operações em 174 caminhos. As tabelas somam 217 linhas porque duas delas, o início e o retorno do fluxo de SSO, pertencem a duas famílias e aparecem nas duas.
Esta página agrupa todas pelo estágio do pipeline a que pertencem, porque é assim que você vai procurar na prática: o problema aparece em um estágio, e você quer os endpoints daquele estágio.
A coluna Exige foi extraída da árvore de dependências da aplicação em execução, não de leitura de código.
Uma permissão nomeada, como integration.write, significa que o papel do dono do token precisa tê-la.
autenticado significa que basta um token válido, sem permissão específica. O recorte por organização continua valendo: você só vê o que está no seu escopo.
pública significa exatamente isso: responde sem token nenhum. São 8 no total, e vale saber quais são.
+ escopo global significa que ser admin não basta, é preciso escopo de plataforma. Admin de uma organização recebe 403.
Um gate que a extração não enxerga
A árvore de dependências não vê verificação escrita dentro do corpo do handler. O caso conhecido é a exigência de escopo global, que em 14 rotas é chamada no corpo, e essas 14 estão marcadas acima porque foram procuradas à parte.
Se você encontrar um 403 num endpoint marcado apenas como autenticado, a causa provável é um gate desse tipo. Vale reportar para a doc ser corrigida.
Quase metade da API é de administrador
92 das 215 operações exigem user.manage, a permissão de criar e remover usuários. Isso inclui coisas que não parecem administrativas, como toda a família de enriquecimento e boa parte da escrita de destinos e rotas.
Vale conferir esta página antes de decidir o papel de um token de automação. Some a isso as três permissões que só o papel admin tem (integration.write, org.manage, secret.read) e a conta fica maior ainda.
Se a tarefa cair numa dessas, não existe recorte por scope que resolva: o papel do dono precisa ser admin.
Os caminhos estão exatamente como o servidor os declara, incluindo a barra final quando existe. Copie daqui em vez de digitar, por causa do redirecionamento explicado em Convenções.
Tudo que traz evento para dentro: as integrações com fornecedores, o estado de cada coletor, recoleta histórica e a ingestão por push.
É aqui que você olha quando a pergunta é "o dado está entrando?".
Pontos de atenção nesta área:
POST /api/collectors/state/{integration_id}/{stream}/trigger dispara coleta de verdade contra a API do fornecedor e consome a quota dele. A resposta devolve só o identificador da tarefa, não o resultado. Repare que o fluxo faz parte do caminho, e que a rota exige apenas token válido: qualquer papel consegue disparar coleta.
reset-cursor faz o coletor recomeçar a partir da janela padrão do fornecedor, tipicamente uma hora atrás. Isso gera duplicidade temporária até o prazo de deduplicação passar. É a operação certa para destravar um coletor parado, e é a única desta família que usa integration.reset.
O backfill tem limites rígidos: janela máxima de 90 dias, e a data inicial não pode estar mais de 90 dias no passado. Integração pai de MSSP é recusada com 422, porque ela não tem fluxo próprio.
test-connection abre conexão real com o fornecedor e registra o resultado no histórico de saúde.
DELETE de integração tem limite de 5 por minuto por usuário. Uma integração pai com filhas ativas devolve 409, a menos que você peça cascata.
pipeline-health não consulta o fornecedor: ele agrega o que já está no banco, com cache de 60 segundos. No agregado de todas as integrações a chave de cache é por usuário; no de uma integração só, a chave é por integração e o cache é compartilhado entre usuários. Nos dois casos um número parado pode ser cache e não estagnação, e o campo cached_at diz de quando é.
Duas rotas degradam em silêncio sem a edição Enterprise: sincronizar tenants responde 200 com um aviso no corpo em vez de erro, e a seleção de tenants grava a escolha sem materializar nada.
POST /api/ingest/{stream} aparece como pública na tabela, e isso merece explicação: ela não é aberta, ela usa outro sistema de autenticação. Em vez de token de gestão, ela valida o token de ingestão da própria integração, que não passa pela árvore de permissões. Veja a comparação na visão geral.
Como o evento cru vira OCSF, e o que fazer quando não vira: mappings e versões, campos novos detectados, e a quarentena.
É aqui que você olha quando o dado entrou mas não chegou ao destino no formato certo.
Pontos de atenção nesta área:
Descartar quarentena é remoção definitiva, sem lixeira. O registro de auditoria e a remoção acontecem na mesma transação.
Descartar e reprocessar compartilham a mesma permissão. Quem pode reprocessar pode apagar.
O descarte em lote aceita até 500 identificadores. Identificador de outra organização aparece como "não encontrado" na lista de erros, em vez de 403, para não permitir varredura.
Se o reprocessamento falhar na normalização, o evento continua na quarentena com o erro atualizado. Ele não é marcado como reprocessado.
Eventos em quarentena expiram sozinhos pelo prazo de retenção, por padrão 7 dias.
Publicar uma versão de mapping vale para os coletores em cerca de 30 segundos. Não há janela de confirmação.
Acrescenta contexto ao evento já normalizado, antes de ele ser roteado.
Pontos de atenção nesta área:
A família inteira exige user.manage. Não há permissão de leitura separada para enriquecimento.
Tabela e política pertencem sempre a uma organização. Não existe recurso global aqui, e a organização é obrigatória.
Compartilhar uma fonte entre organizações exige a edição Enterprise. Sem ela, a resposta é 403 com o código enrichment.source_sharing_requires_enterprise.
O ensaio a seco (dry-run) exercita apenas as regras locais. As regras que consultam serviço externo voltam marcadas como ignoradas, para não gastar cota a cada tecla do operador. Um ensaio verde não prova que a fonte remota responde; para isso existe o teste da fonte.
As métricas têm teto de 180 minutos, porque a série viva só guarda três horas. Pedir uma janela maior devolveria zero, que é indistinguível de "a regra não disparou".
Uma regra inválida é recusada na publicação, com 422. Ela não falha depois, no processamento.
Para onde o evento vai e se chegou: regras de rota, destinos, saúde da entrega e fila de mortos.
É aqui que você olha quando o dado foi normalizado mas não apareceu no SIEM.
Pontos de atenção nesta área:
Criar um destino habilitado cria junto uma rota que já começa a receber evento no ciclo seguinte. Não existe passo de ativação.
Toda rota criada ou editada vale no próximo ciclo de despacho, sem confirmação.
Reordenar rotas exige a lista completa e ordenada. Um identificador fora do seu escopo devolve 403, e um inexistente devolve 404 desfazendo tudo.
POST /{id}/test abre conexão real com o destino e decifra a credencial em memória pela duração do teste.
Revogar a credencial de um destino também desabilita o destino. A entrega para até você configurar a nova chave.
Reprocessar a fila de mortos de um destino global reenvia os eventos de todas as organizações.
Credenciais nunca aparecem em resposta, log ou auditoria. As leituras expõem apenas se existe credencial, não qual é.
A linhagem depende de um recurso opcional. Com ele desligado, a resposta é uma lista vazia, não um erro: vazio aqui não significa "não entregou". Ela vive em cache com prazo de cerca de 7 dias e não serve como arquivo de conformidade.
Na saúde de uma rota, zero eventos casados aparece como ociosa, não como doente.
Consulta ao vivo na fonte do cliente, agendamentos, resultados e triagem de detecções.
Pontos de atenção nesta área:
query.run protege exatamente uma rota nesta superfície: a mudança de status de uma detecção. A execução de consulta ao vivo contra o fornecedor é Enterprise, então no Community essa permissão é mais estreita do que o nome sugere.
Criar agendamento é o gatilho de execução recorrente, e o resultado sai por e-mail só para destinatários da mesma organização.
O eixo de permissão muda dentro da mesma família: criar agendamento exige query.save, mas listar e ver histórico exigem mapping.read.
Ler o histórico de resultados poda resultados vencidos como efeito colateral.
O arquivo CSV de um resultado expira antes do resultado em si. Passado o prazo, o download devolve 410 enquanto o JSON continua visível.
Agendamento fora do seu escopo devolve 404, não 403, para não confirmar que existe.
Em detecções, ler exige apenas token válido, mas mudar o status exige query.run.
Usuários, organizações, tokens, contas de serviço, identidade, licença e configuração da plataforma.
Pontos de atenção nesta área:
Apagar os dados de uma organização é irreversível e exige um texto de confirmação exato no corpo. A limpeza do índice de busca é feita com melhor esforço: se ele estiver fora do ar, o trabalho termina como parcial e o resto conclui.
Apagar uma organização exige escopo global. Ser admin daquela organização não basta.
Criar organização encosta na licença, porque respeita o teto de organizações do plano.
Ativar ou desativar licença muda em tempo real o que a instância inteira pode fazer, e exige admin com escopo global. Um token de licença inválido é recusado com 400 e nunca é armazenado.
No estado da licença, expired_in_grace verdadeiro significa licença já vencida, ainda dentro da carência. As funções continuam ligadas e vão cair depois. Tratar isso como "tudo certo" é o erro clássico.
O histórico geral pede apenas token válido, mas a trilha de auditoria e o CSV dela exigem user.manage.
A captura ao vivo grava eventos reais do cliente, com dados pessoais. A exportação vem mascarada por padrão, e desligar a máscara tira o dado cru do sistema.
A verificação do IRIS faz chamada de saída a cada chamada, então não convém colocá-la em monitor de alta frequência. O estado "não configurado" é válido e não é erro.
Resolução de tenant entre serviços. Não é superfície pública, e não deve ser usada por integração de cliente.
Ela aceita dois modos de autenticação: token com internal.tenant.read, ou uma chave compartilhada em header, que a própria documentação do código marca como obsoleta. Se os dois vierem, o token vence. A resposta traz caminho de credencial e identificador do fornecedor, ou seja, dado sensível de tenant.
Esta página é escrita à mão e pode ficar para trás do código. A fonte que nunca fica é o esquema publicado pela própria instância. Veja Esquema OpenAPI para consultá-lo e gerar um cliente.