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 serverless functions via Identity events.

# Access Identity info via clientContext

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

    exports.handler = async function(event, context) {
      const {identity, user} = context.clientContext;
      // Do stuff and return a response...
    import { Handler } from "@netlify/functions";
    const handler: Handler = async function (event, context) {
      const { identity, user } = context.clientContext;
      // Do stuff and return a response...
    export { handler };
    // Make sure to add code blocks to your code group

    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 serverless functions on Identity events

    You can trigger serverless 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 via Identity.
    • identity-signup: Triggered when an Identity user signs up via Netlify Identity and confirms their email address. Note that this fires for email+password signups only, not for signups via external providers such as Google or GitHub.
    • identity-login: Triggered when an Identity user logs in via Netlify Identity

    To set a synchronous serverless 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 serverless function on identity-login events, name the function file identity-login.js.

    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.js.

    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 looks like:

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

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

    {"app_metadata": {"roles": ["admin"]}}

    The value of the Identity user’s app metadata will be replaced with the above.