Netlify Docs
Ask Netlify

Contact

Platform primitives /Functions /

Functions and Identity

If you have Identity enabled on your site, your serverless functions get access to the Identity instance and to Identity user claims in the context object. You can also trigger functions from Identity events.

# Access Identity info with clientContext

If an Identity service is active for a site, functions running on that site have access to an identity and a user object in Netlify’s base64-encoded custom clientContext. You can access the client context with TypeScript or JavaScript like this:

import type { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

const handler: Handler = async function (
event: HandlerEvent,
context: HandlerContext
) {
  const rawNetlifyContext = context.clientContext.custom.netlify;
  const netlifyContext = Buffer.from(rawNetlifyContext, 'base64').toString('utf-8');
  const { identity, user } = JSON.parse(netlifyContext);
  // Do stuff and return a response...
};

export { handler };


exports.handler = async function (event, context) {
  const rawNetlifyContext = context.clientContext.custom.netlify;
  const netlifyContext = Buffer.from(rawNetlifyContext, 'base64').toString('utf-8');
  const { identity, user } = JSON.parse(netlifyContext);
  // Do stuff and return a response...
};

Visit our docs on Go functions to learn how to access the clientContext with Go.

The user object is present if the function request has an Authorization: Bearer <token> header with a valid JWT from the Identity instance. In this case the object will contain the decoded claims.

The identity object has url and token attributes. The URL is the endpoint for the underlying GoTrue API powering the Identity service. The token attribute is a short-lived admin token that can be used to make requests as an admin to the GoTrue API.

# Trigger functions on Identity events

You can trigger function calls when certain Identity events happen, like when a user signs up. The following events are currently available:

  • identity-validate: Triggered when an Identity user tries to sign up with Identity.
  • identity-signup: Triggered when an Identity user signs up with Netlify Identity and confirms their email address. Note that this fires for email+password signups only, not for signups using external providers such as Google or GitHub.
  • identity-login: Triggered when an Identity user logs in with Netlify Identity

To set a synchronous function to trigger on one of these events, match the name of the function file to the name of the event. For example, to trigger a function on identity-login events, name the function file identity-login.ts.

To trigger a background function on one of the Identity events, include the event name in the function file name. For example, to trigger a background function on identity-login events, name the function file identity-login-background.ts.

If you return a status other than 200, 202, or 204 from one of these event functions, the signup or login will be blocked.

The payload in the body of an Identity event function is formatted like:

{
  "event": "login|signup|validate",
  "user": {
    # an Identity user object
  }
}

If your function returns a 200, you can also return a JSON object with new user_metadata or app_metadata for the Identity user. For example:

import type { Handler, HandlerEvent } from "@netlify/functions";
export async function handler(event: HandlerEvent): Handler {
  const user = JSON.parse(event.body).user;
  return {
    body: JSON.stringify({
      ...user,
      app_metadata: {
        ...user.app_metadata,
        roles: ["admin"],
      },
    }),
    statusCode: 200,
  };
}

export async function handler(event) {
  const user = JSON.parse(event.body).user;
  return {
    body: JSON.stringify({
      ...user,
      app_metadata: {
        ...user.app_metadata,
        roles: ["admin"],
      },
    }),
    statusCode: 200,
  };
}

This function replaces the value of the Identity user’s app_metadata to give them the admin role.

← Background Functions →