RAGJur

Autenticação

Dois mecanismos: API key para integrações server-to-server e OAuth 2.1 para conectores de IA em nome do usuário.

1. API key (x-api-key)

Crie chaves em app.ragjur.ai/painel/chaves. O formato é rj_ + 48 caracteres hexadecimais; apenas o hash SHA-256 é armazenado. Cada chave tem escopos (padrão ragjur:read), limite por minuto e pode ser revogada a qualquer momento.

bash
curl "https://api.ragjur.ai/api/v1/panorama?busca=horas+extras&fonte=tst_jurisprudencia" \
  -H "x-api-key: rj_..."
HTTPSignificado
401Header ausente ou chave inválida ({"error":"Missing x-api-key header"})
403Chave desativada — fale com o suporte
429Rate limit; aguarde Retry-After segundos
Nunca exponha a chave em front-end público ou em repositórios. Consuma a API a partir do seu backend ou de um proxy server-side. O servidor MCP também aceita a chave em Authorization: Bearer rj_….

2. OAuth 2.1 (conectores MCP)

Claude, ChatGPT e Microsoft Copilot conectam-se em nome de cada usuário via OAuth 2.1. O servidor de autorização é embutido no MCP (https://mcp.ragjur.ai) e implementa:

  • RFC 9728 — /.well-known/oauth-protected-resource (descoberta a partir do 401 WWW-Authenticate: Bearer resource_metadata=…).
  • RFC 8414 — /.well-known/oauth-authorization-server.
  • RFC 7591 — registro dinâmico de clientes em /oauth/register; também Client ID Metadata Documents (URL https como client_id).
  • PKCE S256 obrigatório; RFC 8707 resource; iss na resposta (RFC 9207); refresh tokens rotativos (30 dias); revogação (RFC 7009).
  • Escopo único ragjur:read. Access token JWT de 1 h com aud = https://mcp.ragjur.ai/mcp.
EndpointUso
GET https://mcp.ragjur.ai/oauth/authorizeTela de consentimento: o usuário cola a própria API key e autoriza o aplicativo
POST https://mcp.ragjur.ai/oauth/tokenauthorization_code + code_verifier, ou refresh_token
POST https://mcp.ragjur.ai/oauth/registerDCR — devolve client_id (e client_secret se token_endpoint_auth_method ≠ none)
POST https://mcp.ragjur.ai/oauth/revokeRevoga refresh token

Fluxo resumido:

fluxo
Cliente ──POST /mcp (sem token)──▶ 401 + WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"
Cliente ──GET /.well-known/oauth-authorization-server──▶ endpoints, S256, DCR
Cliente ──POST /oauth/register──▶ client_id
Browser ──GET /oauth/authorize?code_challenge=…&resource=https://mcp.ragjur.ai/mcp──▶ consentimento (cole a API key)
Browser ──302 redirect_uri?code=…&state=…&iss=https://mcp.ragjur.ai
Cliente ──POST /oauth/token (code + code_verifier)──▶ access_token (1h) + refresh_token (30d)
Cliente ──POST /mcp  Authorization: Bearer <JWT>──▶ 200

Registrar um cliente confidencial manualmente (ex.: Copilot Studio “Manual”, Custom GPT OAuth, Azure AI Foundry):

bash
curl -X POST https://mcp.ragjur.ai/oauth/register -H 'content-type: application/json' -d '{
  "client_name": "Meu app",
  "redirect_uris": ["https://exemplo.com/oauth/callback"],
  "token_endpoint_auth_method": "client_secret_post",
  "grant_types": ["authorization_code", "refresh_token"]
}'

O token OAuth também é aceito pela API REST em Authorization: Bearer por meio do servidor MCP (REST bridge https://mcp.ragjur.ai/api/tools/<tool>); a API em https://api.ragjur.ai continua exigindo x-api-key diretamente.

3. Boas práticas

  • Uma chave por integração/ambiente; revogue e recrie em vez de compartilhar.
  • Defina rate_limit menor para chaves de demonstração.
  • Registre redirect_uris exatas (comparação literal, HTTPS ou http://localhost).
  • Trate 429 com backoff exponencial; cacheie resultados de jurimetria (mudam lentamente).