Autenticacion

Queria soporta varios metodos de autenticacion para cubrir cada escenario de integracion, desde las aplicaciones web interactivas hasta las integraciones server-to-server.

Metodos de autenticacion

Metodo	Uso principal	Cabecera
JWT Token	Sesiones de usuario (dashboard, app web)	Authorization: Bearer {token}
API Key	Integraciones y widgets	X-API-Key: {key}

JWT (JSON Web Token)

El metodo JWT esta indicado para las aplicaciones web con sesiones de usuario.

Login

curl -X POST https://api.queria.pro/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@empresa.com",
    "password": "password_segura"
  }'

Respuesta:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_9f8e7d6c5b4a3210...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_a1b2c3",
      "email": "usuario@empresa.com",
      "name": "Mario Rossi",
      "role": "COMPANY_ADMIN",
      "companyId": "comp_x1y2z3"
    }
  }
}

El access token tiene una validez de 1 hora. Incluyelo en cada peticion:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Estructura del token

El JWT contiene las siguientes informaciones:

{
  "sub": "usr_a1b2c3",
  "email": "usuario@empresa.com",
  "role": "COMPANY_ADMIN",
  "companyId": "comp_x1y2z3",
  "iat": 1709542800,
  "exp": 1709546400
}

Refresh del token

Antes del vencimiento, renueva el token con el refresh token:

curl -X POST https://api.queria.pro/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_9f8e7d6c5b4a3210..."
  }'

Respuesta:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_a1b2c3d4e5f60000...",
    "expiresIn": 3600
  }
}

Logout

curl -X POST https://api.queria.pro/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Verificar sesion

curl -X GET https://api.queria.pro/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

Las API Key son el metodo recomendado para integraciones server-to-server y widgets.

Formato

Entorno	Prefijo	Ejemplo
Produccion	qk_live_	qk_live_abc123def456ghi789jkl012
Test	qk_test_	qk_test_mno345pqr678stu901vwx234

Uso

Incluye la key en la cabecera X-API-Key:

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{"message": "Cual es la politica de vacaciones?"}'

Generacion

Las API Key se generan desde el dashboard de administracion:

1. Accede a Configuracion en el panel admin
2. Selecciona API Keys
3. Haz clic en Generar Nueva Key
4. Copia inmediatamente la key (se muestra una sola vez)
5. Configura las restricciones (opcional)

Dominios autorizados

Por seguridad, configura los dominios desde los que la API Key puede usarse:

# Dashboard > Configuracion > API Keys > Editar

Dominios autorizados:
- ejemplo.com
- *.ejemplo.com
- app.misitio.com

Las peticiones desde dominios no autorizados recibiran error 403.

Atencion

La eliminacion de una key es inmediata e irreversible. Asegurate de que ninguna integracion la este usando antes de proceder.

OAuth (Social Login)

Queria soporta la autenticacion mediante proveedores OAuth.

Google

curl -X POST https://api.queria.pro/api/auth/google \
  -H "Content-Type: application/json" \
  -d '{"idToken": "google_id_token_here"}'

Microsoft

curl -X POST https://api.queria.pro/api/auth/microsoft \
  -H "Content-Type: application/json" \
  -d '{"accessToken": "microsoft_access_token_here"}'

Ambos devuelven el mismo formato de respuesta del login estandar con accessToken y refreshToken.

Roles y permisos (RBAC)

El sistema usa un modelo RBAC jerarquico para el control de accesos.

Rol	Ambito	Descripcion
COMPANY_ADMIN	Empresa	Gestion usuarios, documentos, configuracion empresarial
COMPANY_EDITOR	Empresa	Upload, modificacion y eliminacion documentos, uso chat
COMPANY_READER	Empresa	Solo lectura documentos y uso chat

Matriz de permisos

Accion	COMPANY_ADMIN	COMPANY_EDITOR	COMPANY_READER
Configuracion Cog-RAG	Si	No	No
Gestion usuarios	Si	No	No
Upload documentos	Si	Si	No
Eliminar documentos	Si	Si	No
Chat IA	Si	Si	Si
Visualizar documentos	Si	Si	Si

Errores de autorizacion

401 Unauthorized - Token faltante o caducado:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token faltante o no valido"
  }
}

403 Forbidden - Permisos insuficientes:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Permisos insuficientes. Rol requerido: COMPANY_ADMIN.",
    "requiredRole": "COMPANY_ADMIN",
    "currentRole": "COMPANY_READER"
  }
}

403 Forbidden - Dominio no autorizado (API Key):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Dominio no autorizado para esta API Key"
  }
}

Best practice de seguridad

Gestion de los tokens

• No guardes los tokens en localStorage (vulnerable a XSS)
• Usa httpOnly cookies cuando sea posible
• Implementa el refresh automatico antes del vencimiento del token

API Key

• No incluyas API Key en el codigo client-side
• Usa variables de entorno para conservar las keys en los servidores
• Rota las keys regularmente (al menos cada 90 dias)
• Limita los dominios autorizados para cada key

Eleccion del metodo

Escenario	Metodo recomendado
Aplicacion web con login de usuario	JWT
Widget incrustado en sitios de terceros	API Key con restriccion de dominio
Integracion server-to-server	API Key
Aplicacion movil	JWT con refresh token
Script de automatizacion	API Key con vencimiento

Reglas fundamentales

• Usa siempre HTTPS para todas las comunicaciones
• Implementa rate limiting client-side para evitar bloqueos
• Monitoriza el uso de las keys desde el dashboard
• Revoca inmediatamente las keys comprometidas