Use Identity in functions

You can use @netlify/identity in Netlify Functions and Edge Functions to verify users, check roles, and manage users programmatically.

Verify the current user

Use getUser() to check whether the request comes from an authenticated user. It returns the User object, or null if the user is not logged in.

Netlify Function

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

Edge Function

import { getUser } from '@netlify/identity'
import type { Context } from '@netlify/edge-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 })
}

Check user roles in functions

The User object includes a roles array from the user’s app_metadata. You can use this to restrict access to specific functions based on a user’s role.

netlify/functions/admin-users.ts

import { getUser, admin } 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 })

  if (!user.roles.includes('admin')) {
    return new Response('Forbidden', { status: 403 })
  }

  // Only admins reach this point
  const users = await admin.listUsers()
  return Response.json({ users })
}

Roles are set on the user’s app_metadata.roles field and included in the JWT. Changes to a user’s roles take effect on their next login or token refresh, not immediately.

Admin operations in functions

The admin export from @netlify/identity provides server-side user management: list, create, update, and delete users. These operations use a short-lived admin token and can only run in Netlify Functions (not in the browser or 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()
  return Response.json({ total: users.length })
}

For the full admin API, refer to the @netlify/identity admin operations documentation.

Server-side login, signup, and logout

You can call login(), signup(), or logout() from a Netlify Function or Edge Function to handle authentication entirely on the server. The library reads and writes the nf_jwt and nf_refresh cookies through the Netlify runtime, so the user’s browser receives the session via the response.

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)
  const { email, password } = await req.json()
  await login(email, password)
  return new Response(null, { status: 302, headers: { Location: '/dashboard' } })
}

Caution

Cross-Site Request Forgery (CSRF) protection. When login(), signup(), or logout() runs inside an HTTP endpoint that you expose, that endpoint needs CSRF protection. Without it, an attacker can trick a victim’s browser into logging into the attacker’s account, then collect anything the victim does inside that session.

Call verifyRequestOrigin(request) at the start of the handler. It compares the request’s Origin header against the request’s own origin and throws a 403 on mismatch. If your framework already checks Origin on state-changing requests by default, the call is redundant but harmless. Refer to the @netlify/identity CSRF protection documentation for the full threat model and the allowedOrigins option.

Identity event functions

Identity event functions are different from the patterns above. Instead of calling @netlify/identity from your function, the Netlify platform calls your function automatically when an Identity event occurs. The function receives a typed event with the user object.

To subscribe to Identity events, export a default object from your function with a method for each event you want to handle. For the broader event-handler pattern, see Trigger functions on events.

Five events are available:

Handler	Triggered when
userValidate	A user attempts to sign up, before the account is created. Use this to block signups based on email domain, rate limiting, or custom validation.
userSignup	A user completes signup (email or external providers). Triggers after email confirmation, if confirmation is enabled. Use this to assign roles, sync to external systems, or send welcome notifications.
userLogin	A user logs in. Use this to track logins, update last-seen timestamps, sync profile data, or block specific users.
userModified	A user’s profile is updated. Use this to validate or react to user changes.
userDeleted	A user is deleted. Notification only.

Event payload

Each handler receives an event with a parsed user object. The fields are camelCase (appMetadata, userMetadata, confirmedAt, etc.).

netlify/functions/identity.mts

import type { UserSignupEvent } from "@netlify/functions"

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

Deny an action

Call event.deny() from a userValidate, userSignup, userLogin, or userModified handler to reject the corresponding action. The end user receives a 401 response and the action is aborted. event.deny() is the canonical way to reject an action — it does not produce an error in observability.

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()
    }
  },
}

If multiple functions subscribe to the same event, the first one to call event.deny() aborts the chain — subsequent functions are not invoked.

Assign roles at signup

Return an object with a user property to modify the user’s record before it’s persisted. This is the most common way to assign roles programmatically.

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"],
        },
      },
    }
  },
}

This sets the member role on every new user. The roles are included in the user’s JWT and can be used for role-based access control with redirect rules.

Tip

You can also set roles through the Netlify UI (on each user’s detail page) or programmatically using admin.updateUser() from @netlify/identity.

Background event functions

Any Identity event handler can run in background mode by setting background: true in the function’s config. The Identity action completes immediately and your handler runs asynchronously — useful for logging or syncing without blocking the user.

netlify/functions/identity.mts

import type { Config, UserLoginEvent } from "@netlify/functions"

export default {
  userLogin(event: UserLoginEvent) {
    // Track the login asynchronously; don't block the user's response.
  },
}

export const config: Config = {
  background: true,
}

Legacy filename convention

Before the typed handler syntax above, Identity event functions used filename matching: identity-validate.ts, identity-signup.ts, identity-login.ts, with a -background suffix for background mode (identity-login-background.ts). That convention is still supported and continues to work. New functions should prefer the typed handler syntax.

With the legacy convention, denial was signaled by returning a non-2xx status (for example, new Response('Not allowed', { status: 403 })). Functions using the new handler syntax should use event.deny() instead.