Add Identity to your project

Add custom login and authentication flows to your project for gated content, member-only experiences, and more using Netlify Identity. Learn your options to set up Netlify Identity using Agent Runners or working locally with code.

Set up with Agent Runners

The fastest way to get started is to use your preferred AI agent through Agent Runners in the Netlify dashboard. When you set up Netlify Identity this way, your AI agent will already know how to enable Netlify Identity for your project, install the necessary packages, and build the authentication flows for your framework. Start a task like “Add user authentication to my project using Netlify Identity” and the agent will handle the setup.

Enable Identity

If you want to set up Identity without using Agent Runners, follow these steps:

1. In the Netlify UI, navigate to Project configuration > Identity for your project.
2. Select Enable Identity.

This creates an Identity service instance for your project and allows you to invite Identity users and change settings.

Note

Previously, we recommended the Netlify Identity widget or the gotrue-js library. For new projects, we recommend @netlify/identity instead. It provides the same authentication capabilities with a simpler API, built-in server-side support, and framework integration.

Install manually

Install the @netlify/identity package to add authentication to your code.

npm install @netlify/identity

The examples and framework-specific examples (Next.js, Astro, Remix, SvelteKit, and more), refer to the @netlify/identity README. Alternatively, here are some of the core authentication flows:

Sign up a user

import { signup } from '@netlify/identity'

const user = await signup('jane@example.com', 'securepassword', {
  full_name: 'Jane Doe',
})

By default, the user receives a confirmation email before they can log in. You can skip this step by enabling autoconfirm in Project configuration > Identity > Emails > Confirmation template.

Log in

import { login } from '@netlify/identity'

const user = await login('jane@example.com', 'securepassword')

Check if a user is logged in

import { getUser } from '@netlify/identity'

const user = await getUser()
if (user) {
  console.log(`Logged in as ${user.email}`)
}

getUser() returns the current user or null. It works in both browser and server contexts (Serverless Functions and Edge Functions). For server-side examples, refer to Use Identity in functions.

Log out

import { logout } from '@netlify/identity'

await logout()

Log in with an external provider

import { oauthLogin } from '@netlify/identity'

// Redirects the browser to the provider's login page
oauthLogin('github')

This works with any external provider you’ve enabled: 'google', 'github', 'gitlab', or 'bitbucket'.

Handle callbacks

After an OAuth redirect, email confirmation, password recovery, or invite acceptance, the user is redirected back to your project with a token in the URL hash. Call handleAuthCallback() on page load to process these tokens.

import { handleAuthCallback } from '@netlify/identity'

const result = await handleAuthCallback()
if (result) {
  // User authenticated via OAuth, email confirmation, recovery, or invite
  console.log(result.type, result.user.email)
}

Without this call, confirmation links and OAuth redirects won’t complete the authentication flow.

Identity requires HTTPS

Identity service requires HTTPS to be secure. If you’re using a custom domain, make sure you have HTTPS working before integrating Identity service with your project.

Next steps

• Refer to the @netlify/identity README for framework-specific examples and the full API reference.
• Use Identity in functions to verify users and check roles on the server side.