Netlify Identity

Auth and user management for a Netlify site without requiring visitors to be Netlify users. Package: @netlify/identity.

Reach for @netlify/identity. Do NOT use the legacy netlify-identity-widget or gotrue-js for new work — same capabilities, simpler API, built-in server-side support.

Footguns — read first

• Identity does not work under netlify dev. Test auth flows on a deploy — Deploy Previews work. Local netlify dev cannot exercise /.netlify/identity/*.
• Never build a from-scratch third-party OAuth flow beside Identity — no provider app registration in code, no client_id/secret in code, no custom callback token exchange. Use oauthLogin() + handleAuthCallback(). Raw OAuth beside Identity is the single most common source of rework.
• Identity config has no public API — dashboard only. Never curl api.netlify.com to flip/inspect Identity settings, never read tokens from ~/Library/Preferences/netlify/config.json, never probe undocumented endpoints.
• RBAC redirects without a fallback = raw 404. A visitor lacking the role gets a bare 404 with no way to log in. Always add a fallback rule.
• Server-side login()/signup()/logout() need CSRF protection. Call verifyRequestOrigin(req) first, or an attacker can log a victim into the attacker's account.
• Site-gating ("lock this site to my company", employees-only) → route to netlify-access-control first. Identity is the app-level user layer only.
• On failure (callback 404s, /.netlify/identity/* unreachable, OAuth doesn't return): surface the error, the dashboard URL, and the setting to check — then stop. Do not invent recovery commands.

Setup

Identity must be enabled in the dashboard first (no API): Project configuration > Identity (https://app.netlify.com/projects/{site_name}/configuration/identity) → Enable Identity.

npm install @netlify/identity

HTTPS is required. On a custom domain, get HTTPS/SSL working before integrating Identity.

Client / universal auth

import { signup, login, logout, getUser, oauthLogin, handleAuthCallback } from '@netlify/identity'

// Sign up — sends a confirmation email by default (skippable via autoconfirm setting)
const user = await signup('[email protected]', 'securepassword', { full_name: 'Jane Doe' })

// Log in / log out
await login('[email protected]', 'securepassword')
await logout()

// Current user — null if not logged in (works in browser + server)
const u = await getUser()
if (u) console.log(u.email)

// OAuth — redirects browser to provider login
oauthLogin('github') // 'google' | 'github' | 'gitlab' | 'bitbucket'

Callback handling is mandatory. Call handleAuthCallback() on your landing page. It processes ALL token types in the URL hash — OAuth redirect, email confirmation, password recovery, invite. Without it, confirmation links and OAuth redirects never complete.

import { handleAuthCallback } from '@netlify/identity'

const result = await handleAuthCallback()
if (result) console.log(result.type, result.user.email) // may be falsy if nothing to process

Other client functions:

• recoverPassword() — complete a password reset (alternative to letting handleAuthCallback() handle the recovery_token).
• acceptInvite() — complete invite acceptance (alternative to handleAuthCallback() handling invite_token).
• refreshSession() — refresh token/session so newly-assigned roles take effect.

Don't hard-code which providers exist. Call getSettings() at startup and render the signup form and OAuth buttons from what it returns.

Server-side (Functions / Edge Functions)

Handlers are modern v2 functions: export default async (req, context) => {}. v1 export { handler } is not supported for getUser()/login()/admin.*.

import { getUser } from '@netlify/identity'
import type { Context } from '@netlify/functions'      // or '@netlify/edge-functions' for Edge

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

getUser() works in browser, Netlify Functions, and Edge Functions.

CSRF — always guard exposed login/signup/logout endpoints:

```ts title="netlify/functions/login.ts" import { login, verifyRequestOrigin } from '@netlify/identity' import type { Context } from '@netlify/functions'

export default async (req: Request, context: Context) => { verifyRequestOrigin(req) // throws 403 on Origin mismatch; supports { allowedOrigins } const { email, password } = await req.json() await login(email, password) return new Response(null, { status: 302, headers: { Location: '/dashboard' } }) }

### admin — Netlify Functions ONLY

`admin.*` uses a short-lived admin token and runs **only in Netlify Functions** — NOT browser, NOT Edge Functions.

import { admin } from '@netlify/identity' import type { Context } from '@netlify/functions'

export default async (req: Request, context: Context) => { const users = await admin.listUsers() // array of users return Response.json({ total: users.length }) }

- `admin.listUsers()` — array of users.
- `admin.updateUser()` — update a user (e.g. roles). Full API: https://www.npmjs.com/package/@netlify/identity

### Session cookies
JWT stored in cookie `nf_jwt`, sent automatically. Server-side `login`/`signup`/`logout` read/write `nf_jwt` and `nf_refresh` via the runtime, so the browser gets the session in the response.

### The `User` object
`id`, `email`, `roles` (array from `app_metadata.roles`, included in the JWT).

## Identity event functions

Functions the platform invokes automatically on Identity events (you don't call them).

**Modern typed-handler syntax** — export a default object with a method per event. Typed handlers require `@netlify/functions` ≥ 5.2.0.

```typescript title="netlify/functions/identity.mts"
import type { UserSignupEvent } from "@netlify/functions"

export default {
  userSignup(event: UserSignupEvent) {
    console.log(`New signup: ${event.user.email}`)
  },
}

Handlers and triggers:

Deny an action: call event.deny() from userValidate/userSignup/userLogin/userModified (NOT userDeleted). User gets a 401; no observability error. With multiple subscribers, the first event.deny() aborts the chain.

```typescript title="netlify/functions/identity.mts" import type { UserValidateEvent } from "@netlify/functions"

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

**Assign roles at signup** — return `{ user: {...} }` to mutate the persisted record. Payload fields are **camelCase** (`appMetadata`, `userMetadata`, `confirmedAt`).

```typescript title="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"] } },
    }
  },
}

Background mode — action completes immediately, handler runs async:

```typescript title="netlify/functions/identity.mts" import type { Config, UserLoginEvent } from "@netlify/functions"

export default { userLogin(event: UserLoginEvent) { / async tracking / } } export const config: Config = { background: true }

Event types from `@netlify/functions`: `UserValidateEvent`, `UserSignupEvent`, `UserLoginEvent`, `UserModifiedEvent`, `UserDeletedEvent`, `Config`.

## Registration & providers (dashboard)

- **Registration preferences** — **Open** (default: any visitor signs up via `signup()`) or **Invite only** (all new users, including external-provider logins, must be invited first).
- **Confirmation:** open registration sends a confirmation email; skip via **Emails > Confirmation template > Configure** (allow signup without verifying email / autoconfirm).
- **External providers** — enable Google/GitHub/GitLab/Bitbucket under **Registration > External providers**. Set your own client ID/secret for branded OAuth (your app name shows on the provider screen). No email confirmation for external-provider signup, but Invite-only still requires an invite.
- **Invitations** — **Project configuration > Identity > Users**; Netlify team users with any role can invite. Invite link carries an `invite_token` → process with `handleAuthCallback()` or `acceptInvite()`.

## Roles & metadata

Stored on the User object; edit in **Identity > Users > Edit settings**:
- **Name** — user-editable: `user_metadata.full_name`.
- **Email** — user-editable; triggers email-change confirmation; changes login credentials: `user_metadata.email`.
- **Roles** — NOT user-editable: `app_metadata.roles`. Read via `getUser()`.

Set roles: at signup via `userSignup` handler returning `{ user: {...} }`; for existing users via `admin.updateUser()` in a Function. **Role changes take effect on next login or token refresh**, not immediately (they don't invalidate the current JWT — client can `refreshSession()`).

## Role-based access control (redirect rules)

Enforced at the CDN edge (no origin round trip). Add a `Role` parameter to redirect rules.

_redirects — ALWAYS include a fallback or non-admins get a raw 404

/admin/ /admin/:splat 200! Role=admin /admin/ /login 401!

multiple roles, comma-chained

/private/* /private/:splat 200! Role=editor,admin

netlify.toml

[[redirects]] from = "/admin/*" to = "/admin/:splat" force = true status = 200 conditions = {Role = ["editor", "admin"]}

Netlify Identity roles resolve at `app_metadata.roles`.

### External JWT provider (Enterprise; alternative to Identity)
You may use Identity **OR** an external JWT provider, **not both** — you cannot authenticate third-party JWT tokens while Identity is enabled. Set the secret at **Project configuration > Access & security > Visitor access > JWT secret** (project-level overrides team-level default).

- Tokens must be **HS256**; header requires `"alg": "HS256"`, `"typ": "JWT"`.
- Payload requires `exp` (future Unix Epoch); other fields optional.
- External-provider roles resolve at `app_metadata.authorization.roles`. Different path → contact support for a custom role path (support-configured, not self-service).

## Emails (Pro+ for customization)

Default sender `[email protected]`. Custom sender (Pro+): set SMTP hostname/port/username/password under **Emails > Outgoing email address** (use SendGrid/Mailjet/etc. for volume).

Custom templates (Pro+): publish HTML to a path on your deployed project, set the path (relative to domain, starting `/`) under **Emails**. Rules: inline CSS only, absolute image links, NO `<html>`/`<head>`/`<body>` tags. Keep template variables intact — don't let your build rewrite them.

Go template variables: `{{ .Email }}`, `{{ .NewEmail }}` (email-change only), `{{ .SiteURL }}`, `{{ .ConfirmationURL }}`, `{{ .Token }}`. Custom link form: `{{ .SiteURL }}/path/#confirmation_token={{ .Token }}` (also `invite_token`, `recovery_token`, `email_change_token`).

## Audit log (Pro+)

**Project configuration > Identity > Identity audit log**. Search with a required scope prefix: `author:[string]` or `action:[string]`. Action names: `login`, `logout`, `user_signedup`, `user_deleted`, `user_modified`, `token_revoked`, `token_refreshed`, `user_recovery_requested`, `user_invited`.

## Plan gating

- Identity itself: all credit-based plans, no extra cost. Unlimited active + invite-only users, custom OAuth credentials, Functions integration — all plans.
- **Pro+ only:** custom outgoing email, custom email templates, Identity audit log.
- **Enterprise only:** external JWT providers.

## Deep guides

- `references/advanced-patterns.md` — SSR / session hydration.
- `references/authorization-and-sessions.md`.

## Legacy (avoid for new work)

- `netlify-identity-widget` / `gotrue-js` — superseded by `@netlify/identity`.
- Legacy event-function filenames (`identity-validate.ts`, `identity-signup.ts`, `identity-login.ts`, `-background` suffix) still work but prefer typed handlers. Legacy denial = return non-2xx status; new code uses `event.deny()`.

<!-- getSettings() referenced in house rules but not documented in sources; its return shape/signature is not specified in the intermediate. -->

<!-- system: agent-context/identity/system.md — human-owned, merged by ctx-gen; edit system.md, not this section -->
# Netlify house rules (identity)

These are org conventions, not docs facts — merged into the rendered skill by
ctx-gen and never generated. Owned by the skills maintainer.

1. Deep guides live in this skill: `references/advanced-patterns.md`
   (SSR/session hydration) and `references/authorization-and-sessions.md`.
2. Identity does not work under `netlify dev` — test auth flows on deploys
   (Deploy Previews work).
3. Identity configuration has no public API — it is dashboard-only. Never curl
   `api.netlify.com` to flip or inspect Identity settings, never read auth
   tokens from `~/Library/Preferences/netlify/config.json`, never probe for
   undocumented endpoints.
4. On failure (callback 404s, `/.netlify/identity/*` unreachable, OAuth flow
   doesn't return), surface the error, the dashboard URL, and the setting to
   check — then stop. Do not invent recovery commands.
5. Never build a from-scratch third-party OAuth flow when Identity is in play —
   no provider app registration, no `client_id`/`secret` in code, no custom
   callback token exchange. Use `oauthLogin()` + `handleAuthCallback()`;
   raw OAuth beside Identity is the single most common source of rework.
6. Server-side `getUser()`/`login()`/`admin.*` require modern v2 functions
   (`export default`) — v1 `export { handler }` is not supported. Typed
   Identity event handlers (`UserSignupEvent`, `event.deny()`) require
   `@netlify/functions` ≥ 5.2.0; older installs use the legacy filenames.
7. Don't hard-code which auth providers exist — call `getSettings()` at
   startup and render the signup form and OAuth buttons from what it returns.
8. Site-gating requests ("lock this site to my company", employees-only)
   route to the netlify-access-control skill first — Identity is the
   app-level user layer only.