Autenticação

Quase todos os endpoints exigem autenticação (a variável NATIVE_WAZUH_REQUIRE_AUTH=true é o padrão). A API aceita quatro mecanismos — use o que fizer sentido para o seu caso de uso.

Métodos suportados

Método	Header	Uso típico
API key	X-API-Key: rfk_… ou Authorization: Bearer rfk_…	Integrações, scripts, CI/CD.
JWT Bearer	Authorization: Bearer <jwt>	SPAs, agentes de usuário após login.
Cookie de sessão	Cookie: ruleforge_session=<jwt>	Navegador acessando o próprio RuleForge.
OIDC/SSO	Fluxo 3-legged, resulta em cookie/JWT	Organizações com IdP corporativo.

Regra prática: para tudo que não é navegador, use API keys. O ciclo de vida é mais simples, os escopos são granulares e não dependem de sessão.

API keys

Formato

Toda API key do RuleForge começa com o prefixo rfk_ seguido de uma string aleatória. Exemplo:

rfk_01HS2XA9CKEB7WZG8RMN2KPQV7_e6c4f2…

Como obter

Uma chave é criada por um administrador da organização na UI (Configurações → Chaves de API) ou via API pelo endpoint POST /platform/organizations/{organization_id}/api-keys. O valor completo aparece apenas uma vez no momento da criação — guarde em um gestor de segredos.

Veja o guia operacional: Chaves de API.

Como enviar

A API aceita o segredo em dois headers — use um dos dois:

X-API-Key: rfk_01HS2XA9CKEB7WZG8RMN2KPQV7_e6c4f2…

ou

Authorization: Bearer rfk_01HS2XA9CKEB7WZG8RMN2KPQV7_e6c4f2…

Se a chave pertencer a um usuário que também é membro de outras organizações, envie também X-Org-Id para fixar o contexto. Para API keys isso normalmente é desnecessário — a chave já é escopada a uma organização.

Escopos

Cada chave tem um conjunto de escopos que restringem o que ela pode fazer. Escolha o menor conjunto suficiente para a integração.

Escopo	Permissões internas
projects:read	Ver projetos, workspaces, versões.
projects:write	projects:read + criar/editar projetos.
rulesets:read	Ler rulesets de um projeto.
rulesets:write	rulesets:read + criar workspaces e editar conteúdo.
analysis:run	Rodar POST /analysis/validate, logtest-native, full.
cases:read	Listar e executar casos de teste.
cases:write	cases:read + criar/editar casos.
reviews:read	Listar revisões.
reviews:write	Abrir revisões, comentar, aprovar.
versions:read	Listar versões.
versions:write	Criar e publicar versões.
admin:*	Conjunto completo da organização (incluindo membros e integrações). Use apenas em automações administrativas controladas.

Se a chave não tem o escopo necessário, a resposta é 403 forbidden com code="forbidden" e mensagem indicando escopo insuficiente.

Ciclo de vida

• Expiração: opcional. Use sempre que for temporário.
• Rotação: POST …/api-keys/{id}/rotate — gera novo segredo, mantém o ID. A chave antiga fica inválida imediatamente.
• Revogação: POST …/api-keys/{id}/revoke — encerra o acesso. Irreversível.

Toda ação é auditada na organização.

Restrição por projeto

Uma chave pode ser criada com project_id — nesse caso ela só autoriza operações no projeto informado. Requisições em outros projetos retornam 403.

JWT Bearer

JWT é emitido pelo POST /auth/login:

{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_at": "2026-04-25T03:30:00Z",
  "user": { "...": "..." }
}

Envie o token em todas as requisições subsequentes:

Authorization: Bearer <jwt>

• TTL padrão: 480 minutos (8 horas), controlado por NATIVE_WAZUH_JWT_TTL_MINUTES.
• Renovação: faça login novamente — não há refresh token neste momento.
• Revogação: POST /auth/logout invalida o jti no servidor; o cookie é limpo e o JWT deixa de ser aceito mesmo antes de expirar.

JWTs do RuleForge não começam com rfk_. Se o seu token começa com rfk_, você está usando uma API key — mande no header X-API-Key ou reconheça que o Bearer rfk_… é tratado como API key pelo servidor.

Cookie de sessão

Quando o login acontece pelo navegador, o servidor define o cookie:

Set-Cookie: ruleforge_session=<jwt>; HttpOnly; SameSite=Lax; Path=/

Flags controladas por envs:

• NATIVE_WAZUH_SESSION_COOKIE_NAME (padrão ruleforge_session)
• NATIVE_WAZUH_SESSION_COOKIE_SECURE (padrão false; true em produção HTTPS)
• NATIVE_WAZUH_SESSION_COOKIE_SAMESITE (lax, strict ou none)
• NATIVE_WAZUH_SESSION_TTL_SECONDS (padrão 900 s — revalidação periódica pelo frontend)

Use cookie apenas quando o cliente for um navegador. Em scripts, prefira API keys ou JWT explícito.

OIDC / SSO corporativo

Organizações com IdP corporativo (Okta, Entra ID, Google Workspace, Keycloak) podem delegar o login:

1. Usuário navega para GET /sso/oidc/{provider_id}/login.
2. O RuleForge redireciona ao IdP.
3. IdP chama de volta GET /sso/oidc/callback.
4. Sessão é criada (cookie) e o usuário é redirecionado à aplicação.

Detalhes dos endpoints em SSO e configuração operacional.

Papéis e permissões (sessão de usuário)

Para usuários autenticados (JWT/cookie), a permissão vem do papel na organização (e papéis específicos de projeto). Resumo:

Papel	O que pode fazer
org_admin	Tudo da organização, incluindo membros, integrações e identity providers.
security_content_lead	Gestão de conteúdo + aprovações.
engineer	Criar e editar conteúdo, rodar análise, abrir revisões e versões.
reviewer	Ver conteúdo, comentar, aprovar.
read_only	Ver e rodar análise.

Consulte Papéis e permissões para detalhes e matriz completa. Para API keys, o que vale é o escopo — papéis não se aplicam.

Requisições não autenticadas

Alguns endpoints são abertos por design:

• GET /api/v1/health — liveness.
• GET /api/v1/product/status — status público do produto.
• GET /healthz — readiness probe (não está sob /api/v1).
• POST /auth/bootstrap — uma única vez, quando a plataforma é zerada.
• POST /auth/login — envia credenciais e recebe JWT.
• GET /billing/plans/public — lista os planos visíveis ao público.
• Endpoints de webhook de entrada (/webhooks/git/*, /billing/webhooks/stripe) — são autenticados via assinatura HMAC.

Tudo o mais exige autenticação.

Erros de autenticação

Código	Quando acontece
401 unauthorized	Token/chave ausente, inválido, expirado ou revogado.
403 forbidden	Autenticado, mas sem permissão (papel ou escopo insuficiente, organização fora do contexto).
429 rate_limited	Muitas tentativas de login ou de registro a partir do mesmo IP/email.

Respostas seguem o envelope de erro padrão. Gere uma nova chave/sessão antes de repetir se recebeu 401.

Links relacionados

• Quickstart
• Endpoints de autenticação
• Gestão de chaves de API
• Chaves de API — guia operacional