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

JavaScript

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:

JavaScript

await dypai.auth.signUp({
  email, password,
  user_data: { full_name: 'Juan Pérez', company: 'Acme' }
});

Iniciar Sesión

JavaScript

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ó:

JavaScript

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:

JavaScript

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:

JavaScript

https://tu-app.com/#access_token=eyJ...&refresh_token=xxx&type=invite

El SDK lo gestiona automáticamente. Al inicializarse:

Revisa window.location.hash en 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_IN o PASSWORD_RECOVERY.

No necesitas código extra — simplemente escucha los eventos de auth:

JavaScript

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_to debe 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(...).

JavaScript

dypai.auth.onAuthStateChange(async (event) => {
  if (event === 'PASSWORD_RECOVERY') {
    await dypai.auth.setPassword('nueva-password-segura');
  }
});

Sin Contraseña (OTP)

Email OTP

JavaScript

// 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

JavaScript

// 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:

JavaScript

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

JavaScript

// 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

JavaScript

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

JavaScript

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

JavaScript

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:

JavaScript

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

JavaScript

// 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:

JavaScript

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

JavaScript

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().

SDK Autenticación

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

JavaScript

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);
}

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:

JavaScript

await dypai.auth.signUp({
  email, password,
  user_data: { full_name: 'Juan Pérez', company: 'Acme' }
});

Iniciar Sesión

JavaScript

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ó:

JavaScript

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:

JavaScript

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:

JavaScript

https://tu-app.com/#access_token=eyJ...&refresh_token=xxx&type=invite

El SDK lo gestiona automáticamente. Al inicializarse:

Revisa window.location.hash en 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_IN o PASSWORD_RECOVERY.

No necesitas código extra — simplemente escucha los eventos de auth:

JavaScript

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_to debe 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(...).

JavaScript

dypai.auth.onAuthStateChange(async (event) => {
  if (event === 'PASSWORD_RECOVERY') {
    await dypai.auth.setPassword('nueva-password-segura');
  }
});

Sin Contraseña (OTP)

Email OTP

JavaScript

// 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

JavaScript

// 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
});

OAuth

Redirige a los usuarios para iniciar sesión con sus cuentas de Google, GitHub u otros proveedores OAuth:

JavaScript

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

JavaScript

// 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

JavaScript

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

JavaScript

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

JavaScript

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:

JavaScript

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

Perfil de Usuario

JavaScript

// 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:

JavaScript

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

JavaScript

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().