SDK Autenticación
El módulo dypai.auth proporciona una forma completa de gestionar el registro de usuarios, el inicio de sesión y la gestión de sesiones. Maneja automáticamente la persistencia del token en localStorage, la renovación en segundo plano, la sincronización entre pestañas y los callbacks de verificación de email.
Necesitas decidir primero el flujo de producto?
Si estas decidiendo si tu app debe permitir signup, onboarding por invitacion o integraciones backend-only, lee primero Flujos de Auth.
Email y Contraseña
Registro (Sign Up)
const { data, error } = await dypai.auth.signUp({
email: 'usuario@ejemplo.com',
password: 'password-segura',
full_name: 'Juan Pérez' // campos extra se envían automáticamente a user_metadata
});
if (error) {
console.error(error.message);
return;
}
if (data.confirmationRequired) {
// La confirmación de email está activada — el usuario debe verificar su email
showMessage('Revisa tu bandeja de entrada para confirmar tu email');
} else {
// Confirmación de email desactivada — el usuario inicia sesión inmediatamente
console.log('Sesión iniciada:', data.user);
}
La confirmación de email está activada por defecto. Cuando está activa, signUp() crea el usuario pero NO inicia sesión. El usuario debe hacer clic en el enlace de confirmación enviado a su email antes de poder iniciar sesión.
Los campos extra como full_name, username o cualquier dato personalizado se fusionan automáticamente en user_metadata. También puedes pasarlos explícitamente mediante user_data:
await dypai.auth.signUp({
email, password,
user_data: { full_name: 'Juan Pérez', company: 'Acme' }
});
Iniciar Sesión
const { data, error } = await dypai.auth.signInWithPassword({
email: 'usuario@ejemplo.com',
password: 'password-segura'
});
if (error) {
// Si el usuario no ha confirmado su email, error.status será 400
console.error(error.message);
return;
}
console.log('Sesión iniciada:', data.user);
signInWithPassword() fallará con un error 400 si el usuario no ha confirmado su email. Muestra un mensaje como "Por favor confirma tu email primero" y ofrece reenviar el email de confirmación.
Reenviar Email de Confirmación
Si un usuario no recibió su email de confirmación o el enlace expiró:
const { data, error } = await dypai.auth.resendConfirmationEmail('usuario@ejemplo.com');
if (!error) {
showMessage('Email de confirmación reenviado — revisa tu bandeja de entrada');
}
Verificación de Email y Callbacks
Cuando un usuario hace clic en un enlace de confirmación, magic link o restablecimiento de contraseña, el servidor de autenticación redirige de vuelta a tu app con tokens en el hash de la URL:
https://tu-app.com/#access_token=eyJ...&refresh_token=xxx&type=signup
Para invitaciones de apps privadas, el patrón es el mismo con type=invite:
https://tu-app.com/#access_token=eyJ...&refresh_token=xxx&type=invite
El SDK lo gestiona automáticamente. Al inicializarse:
- Revisa
window.location.hashen busca de tokens de callback de autenticación. - Si los encuentra: obtiene los datos del usuario, establece la sesión y limpia la URL.
- Emite el evento apropiado:
SIGNED_INoPASSWORD_RECOVERY.
No necesitas código extra — simplemente escucha los eventos de auth:
dypai.auth.onAuthStateChange((event, session) => {
if (event === 'SIGNED_IN') {
router.push('/dashboard');
}
if (event === 'PASSWORD_RECOVERY') {
router.push('/reset-password');
}
});
Invitaciones (Apps Privadas)
Para apps B2B/privadas, la experiencia de invitación debe vivir en la app del cliente (no en el dashboard de DYPAI):
- Tu backend genera un link de invitación en GoTrue (
type=invite). redirect_todebe apuntar a una ruta de callback en la app del cliente (por ejemplo/auth/callback).- Esa ruta debe estar permitida en la allowlist de redirects de GoTrue.
- El SDK detecta el callback de invitación y emite
PASSWORD_RECOVERY. - Muestra un formulario de "crear contraseña" y llama a
dypai.auth.setPassword(...).
dypai.auth.onAuthStateChange(async (event) => {
if (event === 'PASSWORD_RECOVERY') {
await dypai.auth.setPassword('nueva-password-segura');
}
});
Sin Contraseña (OTP)
Email OTP
// 1. Enviar un código de 6 dígitos al email del usuario
await dypai.auth.signInWithOtp({
email: 'usuario@ejemplo.com',
create_user: true // registrar automáticamente si el usuario no existe
});
// 2. El usuario introduce el código
const { data, error } = await dypai.auth.verifyOtp({
email: 'usuario@ejemplo.com',
token: '123456',
type: 'magiclink' // siempre 'magiclink' para email OTP
});
Teléfono (SMS) OTP
// 1. Enviar un código de 6 dígitos por SMS
await dypai.auth.signInWithOtp({
phone: '+34600000000',
create_user: true
});
// 2. El usuario introduce el código
const { data, error } = await dypai.auth.verifyOtp({
phone: '+34600000000',
token: '123456',
type: 'sms' // siempre 'sms' para teléfono OTP
});
El type del OTP debe coincidir con el flujo. Usa 'magiclink' para email OTP, 'sms' para teléfono OTP, y 'signup' para códigos de confirmación de registro. Usar el type incorrecto hará que la verificación falle.
OAuth
Redirige a los usuarios para iniciar sesión con sus cuentas de Google, GitHub u otros proveedores OAuth:
await dypai.auth.signInWithOAuth('google', {
redirectTo: 'https://tu-app.com/auth/callback',
scopes: ['email', 'profile'] // opcional
});
Esto redirige el navegador al proveedor OAuth. Cuando el usuario vuelve a tu app, el SDK recupera automáticamente la sesión desde el callback de la URL.
Recuperación de Contraseña
// 1. Enviar un email de restablecimiento de contraseña
await dypai.auth.resetPasswordForEmail('usuario@ejemplo.com');
// 2. El usuario hace clic en el enlace → el SDK detecta el token de recovery automáticamente
dypai.auth.onAuthStateChange(async (event, session) => {
if (event === 'PASSWORD_RECOVERY') {
// Mostrar formulario de nueva contraseña, luego:
const { data, error } = await dypai.auth.updateUser({
password: 'nueva-password-segura'
});
}
});
Sesión y Usuario
Obtener Sesión
const { data: session, error } = await dypai.auth.getSession();
if (session) {
console.log('Token:', session.access_token);
console.log('Usuario:', session.user);
}
getSession() espera a que la inicialización del SDK termine antes de responder, así que es seguro llamarlo al cargar la página sin condiciones de carrera.
Obtener Usuario Actual
const { data: user, error } = await dypai.auth.getUser();
// o el alias abreviado:
const { data: user, error } = await dypai.me();
Comprobación Rápida Síncrona
if (dypai.auth.isLoggedIn()) {
// El usuario tiene una sesión activa
}
isLoggedIn() es síncrono y puede devolver false durante la inicialización del SDK. Para una comprobación fiable al inicio, usa await dypai.auth.getSession() o onAuthStateChange.
Objeto User y Rol
El SDK normaliza el objeto usuario para que el rol de tu app siempre esté accesible como user.role:
const { data: user } = await dypai.auth.getUser();
user.id // UUID del usuario
user.email // email
user.role // "admin", "editor", "viewer", etc. — el rol de tu app
user.confirmed_at // null si no ha confirmado email
user.role siempre es el rol de tu aplicación, no el rol interno del motor de auth. Internamente, el motor de autenticación (GoTrue) guarda el rol en app_metadata.role. El SDK lo extrae automáticamente a user.role para que no tengas que acceder a user.app_metadata.role manualmente. Esto aplica tanto a dypai.auth.getUser() como a dypai.users.list().
Perfil de Usuario
// Leer usuario actual
const user = dypai.auth.user;
console.log(user.email, user.confirmed_at);
// Actualizar metadatos del usuario
await dypai.auth.updateUser({
data: {
full_name: 'Juan Pérez',
avatar_url: 'https://ejemplo.com/avatar.jpg'
}
});
Listener de Estado de Auth
Reacciona a cambios de autenticación en tiempo real:
const { data: { subscription } } = dypai.auth.onAuthStateChange((event, session) => {
switch (event) {
case 'INITIAL_SESSION':
// Se dispara al inicializar el SDK — sesión recuperada del storage (o null)
break;
case 'SIGNED_IN':
// Usuario inició sesión (contraseña, OTP, OAuth o callback de enlace de email)
break;
case 'SIGNED_OUT':
// Usuario cerró sesión o la sesión expiró
break;
case 'TOKEN_REFRESHED':
// Access token renovado silenciosamente en segundo plano
break;
case 'USER_UPDATED':
// Perfil o contraseña cambiados via updateUser()
break;
case 'PASSWORD_RECOVERY':
// El usuario llegó desde un enlace de reset de contraseña — mostrar formulario
break;
}
});
// Para desuscribirse después:
subscription.unsubscribe();
Cerrar Sesión
await dypai.auth.signOut();
Referencia de Métodos
| Método | Descripción |
|---|---|
signUp(data) | Registrar un nuevo usuario. Devuelve el flag confirmationRequired. |
signInWithPassword(credentials) | Iniciar sesión con email y contraseña. |
signInWithOtp(options) | Enviar código OTP por email o teléfono. |
verifyOtp(params) | Verificar un código OTP e iniciar sesión. |
signInWithOAuth(provider, options) | Redirigir al proveedor OAuth (Google, GitHub, etc.). |
getSession() | Obtener la sesión actual (async, espera la inicialización). |
getUser() | Obtener datos del usuario actual desde el servidor. |
isLoggedIn() | Comprobación síncrona de si existe una sesión. |
updateUser(attributes) | Actualizar email, contraseña o metadatos del usuario. |
setPassword(password) | Establecer/actualizar contraseña del usuario autenticado (flujos invite/recovery). |
resetPasswordForEmail(email) | Enviar un email de restablecimiento de contraseña. |
resendConfirmationEmail(email) | Reenviar el email de confirmación de registro. |
onAuthStateChange(callback) | Escuchar cambios de estado de autenticación. |
signOut() | Limpiar la sesión y cerrar sesión. |
refreshSession() | Renovar manualmente el access token. |
Aliases: login() = signInWithPassword(), register() = signUp(), logout() = signOut(), recoverPassword() = resetPasswordForEmail(), me() = getUser().