Recursos · Autenticación

Documentación de autenticación y ámbitos

Guía lista para producción sobre autenticación JWT/sesión, autenticación por clave de API, encabezados de scope, contexto de espacio de trabajo y reglas de validación.

Volver a la documentación Ir a métodos de autenticación

Métodos de autenticación

Autenticación JWT/sesión para solicitudes en contexto de usuario.
Autenticación por clave API para comunicación entre servicios e integraciones controladas.

Encabezados requeridos

Authorization: Bearer [jwt_token] OR X-API-Key: [api_key]Content-Type: application/jsonX-Scope-Type: personal | workspaceX-Workspace-ID: required only in workspace scope

Modelo de alcance

El alcance personal se ejecuta bajo el contexto del usuario autenticado.
El alcance de espacio de trabajo se ejecuta en un espacio de trabajo específico con controles basados en roles.

Reglas de validación

Si el alcance es personal, no se debe proporcionar X-Workspace-ID.
Si el alcance es de espacio de trabajo, X-Workspace-ID es obligatorio.
Los encabezados de alcance inválidos o conflictivos devuelven 422.

Ejemplo de autenticación 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
  }'

Ejemplo de autenticación con clave 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
  }'

Alcance de espacio de trabajo

json

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

Alcance personal

json

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

Modelos de error

401

Autenticación ausente, expirada o inválida.

403

Alcance no permitido o restricción de rol en el espacio de trabajo.

422

Falló la validación de encabezados/contexto.

429

Límite de solicitudes excedido para el contexto de autenticación actual.