netlify-identity-advanced-patterns

Advanced Identity Patterns

Password Recovery

Three-step flow: request recovery email, handle the callback, then set a new password.

import { requestPasswordRecovery, handleAuthCallback, updateUser, AuthError } from '@netlify/identity'

// Step 1: Send recovery email
async function handleForgotPassword(email: string) {
  try {
    await requestPasswordRecovery(email)
    showSuccess('Check your email for a password reset link.')
  } catch (error) {
    if (error instanceof AuthError) showError(error.message)
  }
}

// Step 2: handleAuthCallback() returns { type: 'recovery', user } — show password reset form
// (See the handleAuthCallback switch in SKILL.md)

// Step 3: Set new password
async function handlePasswordReset(newPassword: string) {
  try {
    await updateUser({ password: newPassword })
    showSuccess('Password updated.')
  } catch (error) {
    if (error instanceof AuthError) showError(error.message)
  }
}

The recovery callback fires a 'recovery' auth event, not 'login'. The user is authenticated but should be prompted to set a new password before navigating away.

Invite Acceptance

When a user clicks an invite link, handleAuthCallback() returns { type: 'invite', user: null, token }. Use the token to accept the invite and set a password.

import { acceptInvite, AuthError } from '@netlify/identity'

async function handleAcceptInvite(token: string, password: string) {
  try {
    const user = await acceptInvite(token, password)
    showSuccess(`Welcome, ${user.email}! Your account is ready.`)
  } catch (error) {
    if (error instanceof AuthError) showError(error.message)
  }
}

Email Change

When a user verifies an email change, handleAuthCallback() returns { type: 'email_change', user } with the change already applied — the returned user carries the new email. The user must be logged in when clicking the verification link.

Like recovery (and unlike invite acceptance), there is no token to consume and no follow-up call — handleAuthCallback() does the work. Handle it in the handleAuthCallback() switch (see SKILL.md) and confirm the new address.