Autenticación

Clione tiene dos modos de autenticación, cada uno para distintos endpoints.

1. JWT (dashboard / admin)

Se emite tras el login del usuario. Se envía como cookies httpOnly + cabecera Authorization: Bearer para compatibilidad cross-origin.

• POST /api/v1/auth/login — email + password → devuelve tokens de access + refresh
• POST /api/v1/auth/refresh — renueva el access token
• POST /api/v1/auth/logout — invalida los tokens actuales (blacklist)
• GET /api/v1/auth/me — usuario actual

Soporta:

• Bloqueo de cuenta (5 intentos fallidos → 15 min de cooldown)
• Rotación de refresh token (los tokens viejos se invalidan)
• 2FA opcional (TOTP + códigos por email) en POST /api/v1/auth/2fa/*
• Google OAuth en POST /api/v1/auth/google

Lo usa el dashboard y las herramientas internas de T42. No se usa para integraciones de storefront.

Flujo 2FA

Cuando un usuario con totpEnabled=true hace login desde un device no-confiado, la respuesta del login es:

{ "requires2FA": true, "tempToken": "...", "methods": ["totp", "email"] }

El cliente entonces llama POST /api/v1/auth/2fa/validate con:

{
  "tempToken": "<del login>",
  "token": "<código de 6 dígitos>",
  "method": "totp",
  "deviceFingerprint": "<opcional — si está, crea un trusted device por 30d>"
}

Otros endpoints 2FA:

Method	Path	Propósito
POST	/2fa/setup	Genera el secreto TOTP + data URL del QR
POST	/2fa/verify-setup	Activa 2FA tras escanear el QR
POST	/2fa/disable	Desactiva 2FA (requiere TOTP actual) + limpia todos los trusted devices
POST	/2fa/email-code	Envía código 6 dígitos por email cuando el usuario perdió el authenticator
POST	/2fa/validate	Valida un código (TOTP o email) y cambia tempToken → sesión completa
GET	/2fa/trusted-devices	Lista los trusted devices del usuario actual (id, userAgent, lastSeenAt, trustedUntil, fingerprintShort)
DELETE	/2fa/trusted-devices/:id	Revoca un trusted device (tenant-scoped — devuelve 404 si no es tuyo)

Los trusted devices se crean cuando el campo deviceFingerprint está presente en la llamada a /2fa/validate. Cada device obtiene una ventana de 30 días; los logins posteriores desde el mismo fingerprint saltan el prompt 2FA y bumpean lastSeenAt.

2. API keys (storefront + server-to-server)

Formato: sk_live_<32-bytes-aleatorios-base64> (prefijo sk_test_ para sandbox).

Crea las keys desde Admin → Apps → [App] → API Keys en el dashboard, o vía:

POST /api/v1/admin/apps/:appId/keys
Authorization: Bearer <JWT>
Content-Type: application/json

{
  "name": "Embed widget — shop.example.com",
  "scopes": ["products:read"],
  "allowedDomains": ["shop.example.com", "*.example.com"]
}

Solo se muestra una vez al crearla. Después solo ves el prefijo de la key.

Cómo usarla

Envíala como cabecera:

Authorization: Bearer sk_live_...

o:

X-API-Key: sk_live_...

Scopes

• products:read — listar y leer productos, categorías, páginas, FAQs
• products:write — reservado para el futuro; aún no se aplica
• mcp:access — acceso al protocolo MCP
• admin — admin completo (no exponer públicamente)

Lista blanca de dominios

Para keys de cara al público (embed widget), el campo allowedDomains valida la cabecera Origin / Referer. Las peticiones desde orígenes no permitidos devuelven 403.

Deja allowedDomains vacío solo para uso server-to-server (sin origen de navegador). Las keys públicas con whitelist vacía generan warnings en logs y endureceremos esto en versiones futuras.

Rotación de keys

• Revoca con PATCH /api/v1/admin/keys/:id { "active": false } — las peticiones existentes con esa key empiezan a devolver 401.
• Genera una nueva key con los mismos scopes + dominios, actualiza el storefront y luego revoca la antigua.