API de Autenticación

La API de Autenticación gestiona todos los flujos de verificación de identidad: login por email/contraseña, registro, actualización de tokens, magic links, autenticación de dos factores y el flujo de código de autorización OAuth2. Los endpoints públicos no requieren un encabezado Authorization; los endpoints de usuario y administrador sí lo requieren.

Email / Contraseña

POST/api/auth/login

Autentica a un usuario con email y contraseña. Devuelve un token de acceso, token de actualización, ID de sesión y expiración del token. Si el tenant o la aplicación requiere 2FA y el usuario tiene 2FA configurado, la respuesta indicará que se requiere un segundo factor antes de emitir los tokens.

Cuerpo de la solicitud


{
  "email": "[email protected]",
  "password": "secret123"
}

Respuesta exitosa (sin 2FA requerido)


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_abc123",
    "tokenType": "Bearer"
  }
}

Respuesta exitosa (2FA requerido)


{
  "ok": true,
  "data": {
    "requiresTwoFactor": true,
    "sessionId": "sess_abc123",
    "availableMethods": ["totp", "sms"]
  }
}

Códigos de error

Código	HTTP	Descripción
`INVALID_CREDENTIALS`	401	El email o la contraseña son incorrectos
`ACCOUNT_LOCKED`	403	La cuenta está bloqueada por fallos repetidos
`ACCOUNT_DISABLED`	403	La cuenta ha sido deshabilitada por un administrador
`RATE_LIMITED`	429	Demasiados intentos de login

POST/api/auth/signup

Registra una nueva cuenta de usuario. El tenant debe tener el registro habilitado. En caso de éxito, devuelve la misma estructura de token que el login. Si el tenant requiere verificación de email, se envía un email y el usuario no puede iniciar sesión hasta que lo verifique.

Cuerpo de la solicitud


{
  "email": "[email protected]",
  "password": "securepassword",
  "firstName": "Jane",
  "lastName": "Doe"
}

firstName y lastName son opcionales. password es requerido a menos que el tenant esté configurado solo para registro sin contraseña.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_xyz789",
    "tokenType": "Bearer"
  }
}

Códigos de error

Código	HTTP	Descripción
`EMAIL_TAKEN`	409	Ya existe una cuenta con este email
`SIGNUP_DISABLED`	403	El tenant ha deshabilitado el registro público
`WEAK_PASSWORD`	400	La contraseña no cumple los requisitos de seguridad
`VALIDATION_ERROR`	400	El cuerpo de la solicitud no pasó la validación de esquema

Endpoint de Token (OAuth2)

POST/api/auth/token

Endpoint de token OAuth2. Soporta múltiples tipos de concesión: Código de Autorización (con PKCE), Credenciales de Cliente (M2M) y Código de Dispositivo. La forma del cuerpo de la solicitud varía según el tipo de concesión.

Este endpoint es el endpoint de token estándar OAuth2 referenciado en el documento de Descubrimiento OIDC. Acepta cuerpos de solicitud en application/json o application/x-www-form-urlencoded.

Concesión: Código de Autorización + PKCE

Se usa para intercambiar un código de autorización (de la redirección del login alojado) por tokens. El code_verifier es el valor aleatorio original del que se derivó el code_challenge.

Cuerpo de la solicitud


{
  "grant_type": "authorization_code",
  "code": "auth_code_from_redirect",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://app.yourdomain.com/callback",
  "client_id": "your-client-id"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "idToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Códigos de error

Código	HTTP	Descripción
`CODE_INVALID`	400	El código de autorización no existe o ha expirado
`CODE_USED`	400	El código de autorización ya ha sido intercambiado (de un solo uso)
`PKCE_MISMATCH`	400	`SHA256(code_verifier)` no coincide con el desafío almacenado
`REDIRECT_URI_MISMATCH`	400	`redirect_uri` no coincide con la URI registrada

Concesión: Credenciales de Cliente (M2M)

Se usa para la autenticación máquina a máquina donde no hay usuario involucrado. El cliente se autentica usando su client_id y client_secret.

Cuerpo de la solicitud


{
  "grant_type": "client_credentials",
  "client_id": "m2m-client-id",
  "client_secret": "m2m-client-secret",
  "scope": "read:users manage:roles"
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "scope": "read:users manage:roles"
  }
}

Concesión: Código de Dispositivo (RFC 8628)

Se usa para dispositivos que no pueden mostrar un navegador (CLIs, IoT, smart TVs). Primero, el dispositivo solicita un código de dispositivo; el usuario luego visita la URL de verificación en un dispositivo separado y aprueba. El dispositivo sondea hasta la aprobación.

Cuerpo de la solicitud (sondeo)


{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "your-client-id"
}

Respuesta pendiente (el usuario aún no ha aprobado)


{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "The user has not yet approved the request. Continue polling."
  }
}

Gestión de Tokens

POST/api/auth/refresh

Intercambia un token de actualización por un nuevo token de acceso y un nuevo token de actualización. Los tokens de actualización se rotan en cada uso — el token de actualización anterior se invalida inmediatamente.

Cuerpo de la solicitud


{
  "refreshToken": "rt_..."
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_new...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Códigos de error

Código	HTTP	Descripción
`REFRESH_TOKEN_INVALID`	401	El token no existe o ha sido revocado
`REFRESH_TOKEN_EXPIRED`	401	El token ha superado su tiempo de expiración

POST/api/auth/validateRequires: authenticated user

Valida el token de acceso actual y devuelve la información del usuario autenticado. Este endpoint también es el endpoint UserInfo de OIDC.

Solicitud: No se requiere cuerpo. El token de acceso se lee del encabezado Authorization: Bearer.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "valid": true,
    "userId": "usr_abc123",
    "email": "[email protected]",
    "username": "jane.doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["viewer", "billing-admin"],
    "tenant": "acme-corp"
  }
}

POST/api/auth/logoutRequires: authenticated user

Invalida la sesión actual. El token de actualización asociado a la sesión se revoca. El token de acceso continúa siendo válido hasta que expire naturalmente (los JWT no se añaden a lista negra por defecto — depender de tiempos de expiración cortos).

Solicitud: No se requiere cuerpo.

Respuesta exitosa


{
  "ok": true,
  "data": { "loggedOut": true }
}

Magic Links (Sin Contraseña)

POST/api/auth/magic-link

Envía un magic link (email de login sin contraseña) a la dirección especificada. Si no existe ninguna cuenta y allowSignup está habilitado en la configuración sin contraseña del tenant, se crea automáticamente una nueva cuenta cuando se hace clic en el enlace.

Cuerpo de la solicitud


{
  "email": "[email protected]",
  "redirectUrl": "https://app.yourdomain.com/callback"
}

redirectUrl es opcional; usa como respaldo la URL de redirección predeterminada configurada en el tenant.

Respuesta exitosa


{
  "ok": true,
  "data": { "sent": true }
}

La respuesta siempre es { sent: true } independientemente de si el email existe, para prevenir la enumeración de usuarios.

POST/api/auth/magic-link/verify

Verifica un token de magic link. Llamado automáticamente por la página de login alojada cuando el usuario hace clic en el enlace. Devuelve tokens en caso de éxito.

Cuerpo de la solicitud


{
  "token": "mlnk_..."
}

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Códigos de error

Código	HTTP	Descripción
`MAGIC_LINK_INVALID`	400	El token está malformado o no existe
`MAGIC_LINK_EXPIRED`	400	El token ha expirado (expiración por defecto: 15 minutos)
`MAGIC_LINK_USED`	400	El token ya ha sido consumido (de un solo uso)

Restablecimiento de Contraseña

POST/api/auth/forgot-password

Inicia un flujo de restablecimiento de contraseña. Envía un email con un enlace de restablecimiento a la dirección especificada. La respuesta siempre es exitosa para prevenir la enumeración de usuarios.

Cuerpo de la solicitud


{
  "email": "[email protected]"
}

Respuesta exitosa


{
  "ok": true,
  "data": { "sent": true }
}

Autenticación de Dos Factores

POST/api/auth/verify-2fa

Verifica un segundo factor después de la autenticación inicial por contraseña. Llama a este endpoint con el ID de sesión devuelto del login (cuando requiresTwoFactor: true) y el código OTP o la respuesta de WebAuthn. En caso de éxito, devuelve tokens de acceso y actualización completos.

Cuerpo de la solicitud — TOTP


{
  "sessionId": "sess_abc123",
  "code": "123456",
  "method": "totp"
}

Cuerpo de la solicitud — SMS OTP


{
  "sessionId": "sess_abc123",
  "code": "789012",
  "method": "sms"
}

Cuerpo de la solicitud — WebAuthn


{
  "sessionId": "sess_abc123",
  "method": "webauthn",
  "response": { }
}

response es el objeto AuthenticatorAssertionResponse de la API WebAuthn del navegador.

Respuesta exitosa


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Códigos de error

Código	HTTP	Descripción
`INVALID_OTP`	400	El código proporcionado es incorrecto
`OTP_EXPIRED`	400	El código ha expirado
`SESSION_INVALID`	400	El ID de sesión es inválido o ya fue consumido
`WEBAUTHN_FAILED`	400	La verificación de la aserción WebAuthn falló

GET/api/auth/check-2fa-requiredRequires: authenticated user

Verifica si la sesión actual requiere verificación 2FA antes de conceder acceso completo. Útil para proteger páginas después del login inicial y asegurar que el usuario completó el flujo completo.

Respuesta


{
  "ok": true,
  "data": {
    "required": false,
    "verified": true,
    "availableMethods": ["totp", "sms"]
  }
}

Detección SSO

POST/api/auth/sso/detect

Detecta si el dominio de email de un usuario tiene una conexión SSO Empresarial configurada. Úsalo para implementar formularios de login “inteligentes” que redirijan automáticamente a los usuarios empresariales a su proveedor SSO en lugar de mostrar el campo de contraseña.

Cuerpo de la solicitud


{
  "email": "[email protected]"
}

Respuesta — SSO disponible


{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://api.altovar.net/api/auth/sso/login/enterprise-alias"
  }
}

Respuesta — sin SSO


{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

Endpoint de Autorización OAuth2

POST/api/oauth/authorize

Inicia un flujo de Código de Autorización + PKCE de OAuth2. Este endpoint crea una sesión y redirige al usuario a la página de login alojada de Auris. En una autenticación exitosa, Auris redirige al redirect_uri registrado con un código de autorización.

Esto típicamente se activa como una redirección del navegador (GET o formulario POST) en lugar de una llamada fetch. El método del SDK loginWithRedirect() gestiona todo esto automáticamente.

Parámetros (cadena de consulta o cuerpo de la solicitud)

Parámetro	Requerido	Descripción
`response_type`	Sí	Debe ser `"code"`
`client_id`	Sí	Client ID de la aplicación
`redirect_uri`	Sí	URL de callback (debe estar registrada)
`state`	Sí	Token CSRF aleatorio
`code_challenge`	Sí	BASE64URL(SHA256(code_verifier))
`code_challenge_method`	Sí	Debe ser `"S256"`
`scope`	No	Scopes separados por espacios (p. ej., `openid profile email`)
`login_hint`	No	Pre-rellenar el campo de email
`screen_hint`	No	`"signup"` para mostrar la pantalla de registro primero
`locale`	No	Forzar un idioma específico (`en`, `it`, `de`, `fr`, `es`)
`prompt`	No	`"login"` para forzar re-autenticación

Redirección en caso de éxito


https://app.yourdomain.com/callback?code=auth_code_xxx&state=original_state

Redirección en caso de error


https://app.yourdomain.com/callback?error=access_denied&error_description=User+cancelled&state=original_state

Códigos de error (devueltos como parámetros de redirección)

Código	Descripción
`invalid_request`	Parámetro faltante o inválido
`unauthorized_client`	`client_id` no encontrado o `redirect_uri` no registrado
`access_denied`	El usuario canceló la autenticación
`invalid_scope`	El scope solicitado no está permitido

Relacionado

OAuth 2.0 y OIDC — Fundamentos del protocolo detrás de los endpoints de autenticación
Tokens Explicados — Tokens de acceso, actualización e ID en detalle
Flujo PKCE — Cómo funciona el intercambio de Código de Autorización + PKCE
Guía de Login Alojado — Integra el login alojado con tu aplicación
Magic Links — Autenticación por email sin contraseña
Login Social — Configura proveedores de identidad de terceros
Credenciales M2M Client Credentials — Autenticación servidor a servidor
Configuración de Autenticación — Configurar MFA, sin contraseña y login social desde la Consola