Recursos · Autenticação

Documentação de Autenticação e Escopos

Guia pronto para produção sobre autenticação JWT/sessão, autenticação por chave de API, cabeçalhos de escopo, contexto de workspace e regras de validação.

Voltar à documentação Ir para Métodos de Autenticação

Métodos de Autenticação

Autenticação JWT/sessão para requisições com contexto de usuário.
Autenticação por chave de API para integrações entre serviços e integrações controladas.

Cabeçalhos Obrigatórios

Authorization: Bearer [jwt_token] OU X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: obrigatório apenas no escopo workspace

Modelo de Escopos

O escopo personal é executado no contexto do usuário autenticado.
O escopo workspace é executado dentro de um workspace específico, com controles baseados em papéis.

Regras de Validação

Se o escopo for personal, não deve ser fornecido o X-Workspace-ID.
Se o scope for workspace, o cabeçalho X-Workspace-ID é obrigatório.
Cabeçalhos de scope inválidos ou conflitantes retornam 422.

Exemplo de Autenticação JWT

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [jwt_token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Hello from JWT auth",
    "stream":false
  }'

Exemplo de autenticação por chave de API

bash

curl -X POST "/api/v1/chat/completions" \
  -H "X-API-Key: [api_key]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -d '{
    "message":"Hello from API key auth",
    "stream":false
  }'

Escopo do workspace

json

{
  "headers": {
    "X-Scope-Type": "workspace",
    "X-Workspace-ID": "[workspace_uuid]"
  },
  "note": "Workspace scope requires workspace id."
}

Escopo pessoal

json

{
  "headers": {
    "X-Scope-Type": "personal"
  },
  "note": "Personal scope must not include workspace id."
}

Modelos de Erro

401

Autenticação ausente, expirada ou inválida.

403

Scope não autorizado ou restrição de função no workspace.

422

Falha na validação do cabeçalho/contexto.

429

Limite de requisições excedido para o contexto de autenticação atual.