---
name: netlify-identity
description: Use whenever the task involves authentication, signups, logins, password recovery, user accounts, role-based access control, OAuth providers, protected routes, protecting Netlify Functions, server-side auth in SSR frameworks, or Netlify Identity. Always use `@netlify/identity`. Never use `netlify-identity-widget` or `gotrue-js` as they are deprecated. Make sure to always run `node scripts/enable.cjs` located in this skill's directory after implementing Netlify Identity.
---

# Netlify Identity

Netlify Identity is a user management service for signups, logins, password recovery, user metadata, and role-based
access control. It is built on [GoTrue](https://github.com/netlify/gotrue) and issues JSON Web Tokens (JWTs).

## Enable Feature

After implementing Netlify Identity, you **must** run the enable script to activate the feature on the deploy. The script
is located in this skill's `scripts/` directory:

```bash
node scripts/enable.cjs
```

**NEVER use `netlify-identity-widget` or `gotrue-js`. Always use `@netlify/identity`.** It provides a unified, headless
TypeScript API that works in both browser and server contexts (Netlify Functions, Edge Functions, SSR frameworks). It
replaces all previous Identity client libraries.

## Setup

```bash
npm install @netlify/identity
```

Identity is enabled on the site when you run the enable script above. Default settings:

- **Registration** - Open (anyone can sign up). Change to Invite only in **Project configuration > Identity** if needed.
- **Autoconfirm** - Off (new signups require email confirmation). Enable in **Project configuration > Identity** to skip
  confirmation during development.

For local development, use `netlify dev` so the Identity endpoint is available.

## Quick Start

Log in from the browser:

```typescript
import { login, getUser } from '@netlify/identity'

const user = await login('jane@example.com', 'password123')
console.log(`Hello, ${user.name}`)

// Later, check auth state
const currentUser = await getUser()
```

Protect a Netlify Function:

```typescript
// netlify/functions/protected.mts
import { getUser } from '@netlify/identity'
import type { Context } from '@netlify/functions'

export default async (req: Request, context: Context) => {
  const user = await getUser()
  if (!user) return new Response('Unauthorized', { status: 401 })
  return Response.json({ id: user.id, email: user.email })
}
```

## Error Handling

`@netlify/identity` throws two error classes:

- **`AuthError`** - Thrown by auth operations (login, signup, logout, etc.). Has `message`, optional `status` (HTTP
  status code from GoTrue), and optional `cause` (original error).
- **`MissingIdentityError`** - Thrown when Identity is not configured in the current environment (site doesn't have
  Identity enabled, or not running via `netlify dev`).

`getUser()` and `isAuthenticated()` never throw - they return `null` and `false` respectively on failure.

### Try/Catch Pattern

```typescript
import { login, AuthError, MissingIdentityError } from '@netlify/identity'

try {
  const user = await login(email, password)
} catch (error) {
  if (error instanceof MissingIdentityError) {
    // Identity not configured - show setup instructions
    showError('Identity is not enabled on this site.')
    return
  }
  if (error instanceof AuthError) {
    switch (error.status) {
      case 401:
        showError('Invalid email or password.')
        break
      case 403:
        showError('Signups are not allowed for this site.')
        break
      case 422:
        showError('Invalid input. Check your email and password.')
        break
      case 404:
        showError('User not found.')
        break
      default:
        showError(error.message)
    }
    return
  }
  throw error
}
```

### Common Status Codes

| Status | Meaning |
|--------|---------|
| 401 | Invalid credentials or expired token |
| 403 | Action not allowed (e.g., signups disabled) |
| 422 | Validation error (e.g., weak password, malformed email) |
| 404 | User or resource not found |

## Authentication Flows

### Login

```typescript
import { login, AuthError } from '@netlify/identity'

let loading = false

async function handleLogin(email: string, password: string) {
  loading = true
  try {
    const user = await login(email, password)
    showSuccess(`Welcome back, ${user.name ?? user.email}`)
  } catch (error) {
    if (error instanceof AuthError) {
      showError(error.status === 401 ? 'Invalid email or password.' : error.message)
    }
  } finally {
    loading = false
  }
}
```

### Signup

After signup, check `user.emailVerified` to determine if the user was auto-confirmed (logged in immediately) or needs
to confirm their email first.

```typescript
import { signup, AuthError } from '@netlify/identity'

async function handleSignup(email: string, password: string, name: string) {
  try {
    const user = await signup(email, password, { full_name: name })
    if (user.emailVerified) {
      // Autoconfirm is ON - user is logged in
      showSuccess('Account created. You are now logged in.')
    } else {
      // Autoconfirm is OFF - confirmation email sent, user is NOT logged in
      showSuccess('Check your email to confirm your account.')
    }
  } catch (error) {
    if (error instanceof AuthError) {
      showError(error.status === 403 ? 'Signups are not allowed.' : error.message)
    }
  }
}
```

When autoconfirm is off, the confirmation email contains a link that redirects the user back to the site with
`#confirmation_token=<token>` in the URL hash. `handleAuthCallback()` processes this automatically - it calls
`confirmEmail()` under the hood, logs the user in, and returns `{ type: 'confirmation', user }`. This is why
`handleAuthCallback()` must be called on page load (see the OAuth section below for the full switch).

### OAuth

OAuth is a two-step flow: `oauthLogin(provider)` redirects away from the site, then `handleAuthCallback()` processes
the redirect when the user returns.

```typescript
import { oauthLogin } from '@netlify/identity'

// Step 1: Redirect to OAuth provider (this navigates away - never returns)
function handleOAuthClick(provider: 'google' | 'github' | 'gitlab' | 'bitbucket') {
  oauthLogin(provider)
}
```

```typescript
import { handleAuthCallback, AuthError } from '@netlify/identity'

// Step 2: Process the redirect on page load
async function processCallback() {
  try {
    const result = await handleAuthCallback()
    if (!result) return // No callback hash present - normal page load

    switch (result.type) {
      case 'oauth':
        showSuccess(`Logged in as ${result.user?.email}`)
        break
      case 'confirmation':
        showSuccess('Email confirmed. You are now logged in.')
        break
      case 'recovery':
        // User is authenticated but must set a new password
        showPasswordResetForm(result.user)
        break
      case 'invite':
        // User must set a password to accept the invite
        showInviteAcceptForm(result.token)
        break
      case 'email_change':
        showSuccess('Email address updated.')
        break
    }
  } catch (error) {
    if (error instanceof AuthError) {
      showError(error.message)
    }
  }
}
```

Always call `handleAuthCallback()` on page load in any app that uses OAuth, password recovery, invites, or email
confirmation. It handles all callback types via the URL hash.

### Password Recovery

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

```typescript
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 above)

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

Note: 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.

```typescript
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 }`. This requires an
active browser session - the user must be logged in when clicking the verification link.

```typescript
import { verifyEmailChange, AuthError } from '@netlify/identity'

// If you need to verify programmatically with a token:
async function handleEmailChangeVerification(token: string) {
  try {
    const user = await verifyEmailChange(token)
    showSuccess(`Email updated to ${user.email}`)
  } catch (error) {
    if (error instanceof AuthError) showError(error.message)
  }
}
```

### Session Hydration

`hydrateSession()` bridges server-set cookies to the browser session. Call it on page load when using server-side login
(e.g., login inside a Netlify Function followed by a redirect).

```typescript
import { hydrateSession } from '@netlify/identity'

// On page load
const user = await hydrateSession()
if (user) {
  // Browser session is now in sync with server-set cookies
}
```

Note: `getUser()` auto-hydrates from the `nf_jwt` cookie if no browser session exists, so explicit `hydrateSession()`
is only needed when you want to restore the full session (including token refresh timers) after a server-side login.

## Auth Events

Subscribe to auth state changes with `onAuthChange`. Returns an unsubscribe function. No-op on server.

```typescript
import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'

const unsubscribe = onAuthChange((event, user) => {
  switch (event) {
    case AUTH_EVENTS.LOGIN:
      console.log('User logged in:', user?.email)
      break
    case AUTH_EVENTS.LOGOUT:
      console.log('User logged out')
      break
    case AUTH_EVENTS.TOKEN_REFRESH:
      // Token auto-refreshed in background
      break
    case AUTH_EVENTS.USER_UPDATED:
      console.log('User profile updated:', user?.email)
      break
    case AUTH_EVENTS.RECOVERY:
      // Recovery token processed - prompt for new password
      console.log('Password recovery initiated')
      break
  }
})

// Later: unsubscribe()
```

Auth events are automatically detected across browser tabs via the storage event listener - no extra setup needed.

## Settings-Driven UI

Fetch the project's Identity settings to conditionally render signup forms and OAuth buttons.

```typescript
import { getSettings } from '@netlify/identity'

const settings = await getSettings()
// settings.autoconfirm - boolean, whether email confirmation is skipped
// settings.disableSignup - boolean, whether registration is closed
// settings.providers - Record<AuthProvider, boolean>, e.g. { google: true, github: true, ... }

// Conditionally render signup
if (!settings.disableSignup) {
  showSignupForm()
}

// Conditionally render OAuth buttons
for (const [provider, enabled] of Object.entries(settings.providers)) {
  if (enabled) {
    showOAuthButton(provider)
  }
}
```

## Full API Reference

For the complete API reference - all function signatures, type definitions, OAuth helpers, admin operations, session
management, auth events, and framework-specific integration examples - read the package README:

```
node_modules/@netlify/identity/README.md
```

The README is shipped with the npm package and is always in sync with the installed version.

## SSR Integration Patterns

For SSR frameworks, the recommended pattern is:

- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`

Browser-side auth mutations set the `nf_jwt` cookie and localStorage, and emit `onAuthChange` events. The
server reads the cookie on the next request.

The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these
require the Netlify Functions runtime to set cookies. After a server-side mutation, use a full page navigation so the
browser sends the new cookie.

Always use `window.location.href` (not framework router navigation) after server-side auth mutations in Next.js,
TanStack Start, and SvelteKit. Remix `redirect()` is safe because Remix actions return real HTTP responses.

## Identity Event Functions

Subscribe to Identity lifecycle events by exporting an object whose properties are named event handlers. See the
**netlify-functions** skill for the full event-handler pattern.

**Available identity handlers:**

| Handler | Trigger |
|---|---|
| `userValidate` | A user attempts to sign up. Can deny the signup. |
| `userSignup` | A user completes signup. Can deny or mutate. |
| `userLogin` | A user logs in. Can deny or mutate. |
| `userModified` | A user's profile is updated. Can deny or mutate. |
| `userDeleted` | A user is deleted. Notification only. |

Each handler receives a typed event with a parsed `user` object (camelCase fields: `appMetadata`, `userMetadata`,
`confirmedAt`, etc.).

### Example: Assign Default Role on Signup

Return `{ user: ... }` to substitute the user record before it's persisted.

```typescript
// netlify/functions/identity.mts
import type { UserSignupEvent } from '@netlify/functions'

export default {
  userSignup(event: UserSignupEvent) {
    return {
      user: {
        ...event.user,
        appMetadata: {
          ...event.user.appMetadata,
          roles: ['member'],
        },
      },
    }
  },
}
```

### Deny an Action

Call `event.deny()` to reject a signup, login, validation, or modification. The end user receives a 401. Do NOT throw —
`event.deny()` is the canonical denial mechanism and does not produce an error in observability.

```typescript
import type { UserValidateEvent } from '@netlify/functions'

export default {
  userValidate(event: UserValidateEvent) {
    if (!event.user.email?.endsWith('@example.com')) {
      return event.deny()
    }
  },
}
```

If multiple functions subscribe to the same event, the first to call `event.deny()` aborts the chain.

For bulk user management or role changes outside lifecycle events, use the `admin` API instead of Identity event functions.

**Legacy filename convention:** The previous syntax — files named `identity-validate.ts`, `identity-signup.ts`, or
`identity-login.ts` (with a `-background` suffix for background mode), exporting `handler` and signaling denial via a
non-2xx response — still works. New functions should prefer the typed handler syntax above.

## Roles and Authorization

### First Admin User

The first admin user cannot be created through code alone. You must direct the user to set it up through the Netlify UI:

1. Go to **Identity** in the project sidebar in the Netlify dashboard
2. Click **Invite users** and enter the admin user's email address
3. After the user accepts the invite, click the user in the Identity list to open their detail page
4. In the **Roles** field, add the `admin` role and save

Once the first admin exists, subsequent users can be managed programmatically using Identity event functions (e.g., assigning roles in the `userSignup` handler) or role-based redirects.

### Metadata Types

- **`app_metadata.roles`** - Server-controlled. Only settable via the Netlify UI, admin API, or Identity event functions.
  Do not allow users to set their own roles.
- **`user_metadata`** - User-controlled. Users can update this via `updateUser({ data: { ... } })`.

### Role-Based Redirects

Use `netlify.toml` to restrict paths by role:

```toml
[[redirects]]
  from = "/admin/*"
  to = "/admin/:splat"
  status = 200
  conditions = { Role = ["admin"] }

[[redirects]]
  from = "/admin/*"
  to = "/"
  status = 302
```

Rules are evaluated top-to-bottom. The first redirect matches users with the `admin` role; everyone else falls through
to the second rule and is redirected away.

**How it works:** The `nf_jwt` cookie is read by the CDN to evaluate `conditions = { Role = [...] }`. Without this
cookie, role-based redirects will not work.

## Common Errors & Solutions

### "Signups not allowed for this instance" (403)

**Cause:** Registration is set to Invite only.

**Fix:**

1. Change to Open in **Project configuration > Identity**
2. Or invite users from the Identity tab in the Netlify UI

```typescript
if (error instanceof AuthError && error.status === 403) {
  showError('Signups are disabled. Contact the site admin for an invite.')
}
```

### Invalid credentials (401)

**Cause:** Wrong email or password on login.

**Fix:** Show a user-facing error and let the user retry. Do not reveal whether the email or password was wrong.

```typescript
if (error instanceof AuthError && error.status === 401) {
  showError('Invalid email or password.')
}
```

### "Email not confirmed"

**Cause:** User tries to log in before confirming their email (autoconfirm is off).

**Fix:** Tell the user to check their inbox. Optionally provide a way to resend the confirmation email via `signup()`
with the same credentials.

### "Token expired" / 401 on API calls

**Cause:** Stale access token.

**Fix:**

1. Always use `getUser()` before authenticated requests - it auto-hydrates from cookies
2. In the browser, the library auto-refreshes tokens via `startTokenRefresh()`
3. On the server, call `refreshSession()` in middleware to handle near-expiry tokens

```typescript
const newToken = await refreshSession()
if (newToken) {
  // Token was refreshed - retry the request
}
```

### Identity event function not triggering

**Cause:** Export shape does not match the expected pattern.

**Fix:**

1. Use the typed handler syntax: default export an object with `userSignup`, `userLogin`, `userValidate`, `userModified`,
   or `userDeleted` methods
2. Place the function in `netlify/functions/` with `.mts` or `.mjs` extension
3. If using the legacy filename convention, verify the filename matches the event exactly (`identity-signup.mts`,
   `identity-validate.mts`, or `identity-login.mts`) and that the file exports a named `handler`

### `MissingIdentityError`

**Cause:** Identity is not configured in the current environment.

**Fix:**

1. Ensure Identity is enabled on the project
2. Use `netlify dev` for local development so the Identity endpoint is available

```typescript
if (error instanceof MissingIdentityError) {
  showError('Identity is not enabled. Run "netlify dev" or enable Identity in project settings.')
}
```

### `AuthError` on server - missing Netlify runtime

**Cause:** Server-side `login()`, `signup()`, or `logout()` require the Netlify Functions runtime to set cookies.

**Fix:**

1. Deploy to Netlify to use server-side auth mutations
2. Or use `netlify dev` for local development

### "User not found" after OAuth login

**Cause:** OAuth provider is not enabled for the project.

**Fix:**

1. Enable the provider in **Project configuration > Identity > External providers**
2. Users are created automatically on first OAuth login

### Account operations fail after server-side login

**Cause:** Browser-side session is not bootstrapped from server-set cookies.

**Fix:** Call `hydrateSession()` on page load to bridge server-set cookies to the browser session. Then use
`updateUser()`, `verifyEmailChange()`, or other account operations.

```typescript
import { hydrateSession, updateUser } from '@netlify/identity'

// On page load after server-side login
await hydrateSession()

// Now account operations work
await updateUser({ data: { full_name: 'Jane' } })
```

### "Email change verification requires an active browser session"

**Cause:** `verifyEmailChange()` was called without an active session. The user must be logged in when clicking the
email change verification link.

**Fix:** Ensure the user is logged in before processing the `email_change` callback. If the session expired, prompt
the user to log in first.

### "No user is currently logged in"

**Cause:** An account operation (`updateUser`, `verifyEmailChange`) was called without an authenticated user.

**Fix:** Check `getUser()` before calling account operations. If `null`, redirect to login.

```typescript
const user = await getUser()
if (!user) {
  redirectToLogin()
  return
}
await updateUser({ data: { full_name: 'Jane' } })
```

### Stale session - user deleted server-side

**Cause:** `getUser()` returns `null` when the `nf_jwt` cookie is gone but localStorage still has a stale
session. This happens when a user is deleted via the admin API or Netlify UI.

**Fix:** `getUser()` handles this gracefully - it returns `null` and the stale localStorage entry is ignored. Always
check for `null` before using the user object.
