# JWT Populate Lambda

Learn how to add custom claims to the access tokens and Id tokens FusionAuth issues.

> For the index of this section of the site, see [llms.txt](https://fusionauth.io/docs/llms.txt)

If you would like to augment the claims provided in the JWT before it has been signed you can specify a lambda in the JWT configuration. This lambda will be invoked prior to the token being signed and issued to a user.

Here's a brief video showing how to set up a JWT populate lambda:

[Play](https://youtube.com/watch?v=xFp1QkTiOAU)

When you create a new lambda using the FusionAuth UI we will provide you an empty function for you to implement.

This lambda is not executed if you call the Login API directly and omit the **applicationId** request parameter.

## Lambda Structure

If you are using the API to create the lambda you will need to ensure your function has the following signature:

```javascript
function populate(jwt, user, registration, context) {
  // Lambda code goes here
}
```

This lambda must contain a function named **populate** that accepts the following parameters:

*   `jwt` - the claims object to be signed and return as the JWT payload. You can modify this object.
*   `user` - the FusionAuth User object. This object is read-only.
*   `registration` - the FusionAuth UserRegistration object. This parameter will be `undefined` when the user is not registered for the application. This object is read-only.
*   `context` - Available since `1.59.0` - an object containing the context of the request, including access to [secrets](https://fusionauth.io/docs/lambdas.md#secrets). This object is read-only.

### `jwt` object

You may add or modify anything in the `jwt` object. However, you may not modify the header or certain reserved claims. When adding a custom claim to the JWT, always use a namespace to avoid clashes with future standard or FusionAuth-specific claims. The following claims are considered reserved and modifications or removal will not be reflected in the final JWT payload:

*   `act` - Available since `1.70.0` - Actor claim chain (managed by Token Exchange)
*   `amr`
*   `auth_time`
*   `cnf`
*   `exp`
*   `gty`
*   `iat`
*   `sub`
*   `tid`
*   `tty`

Note that as of version `1.59.0`, you may modify the `exp` claim as long as the new value does not increase the lifetime of the token. So you may use this behavior to optionally reduce the time-to-live of this token. This may be useful when using a single FusionAuth application and in some contexts you wish to reduce the lifetime of a token. As an example, when using an OAuth grant, the requested scopes are available to the lambda function and could be used as an indicator to reduce the time-to-live of this token.

### `user` and `registration` objects

The two FusionAuth objects are well documented in the [User API](https://fusionauth.io/docs/apis/users.md) and [Registration API](https://fusionauth.io/docs/apis/registrations.md) documentation. The JWT object is a JavaScript object containing the JWT payload. See [OpenID Connect & OAuth 2.0 Token](https://fusionauth.io/docs/authentication/oauth/tokens.md).

### `context` object

The context object includes the following:

*   `authenticationType` - Available since `1.70.0` - the authentication method used (e.g., `PASSWORD`, `REFRESH_TOKEN`, `PASSWORDLESS`, `JWT_SSO`).
*   `scopes` - Available since `1.59.0` - array of scopes that were requested for the token.
*   `services.secrets` - Available since `1.64.0` - provides access to [secrets](https://fusionauth.io/docs/lambdas.md#secrets).

## Assigning The Lambda

Once a lambda is created, you must assign it to an Application. See the JWT tab in the Application configuration.

## Example Lambda

Here is an example of a simple Lambda that adds a few extra claims to the JWT issued to the User.

```javascript
function populate(jwt, user, registration) {
  // Add a new claim named 'favoriteColor' from a custom data attribute on the user
  jwt.favoriteColor = user.data.favoriteColor;
  // Add a new claim named 'dept' using a custom data attribute on the registration
  jwt.dept = registration.data.departmentName;

  // Create an event log of type 'Debug' when the lambda has debug logging enabled
  console.debug('Added custom claims to the JSON web token');
}
```

Related

[Lambdas Lambdas Learn about lambdas, the JavaScript functions that customize how FusionAuth logs users in and issues tokens. fusionauth lambdajavascriptcustom claims](https://fusionauth.io/docs/lambdas.md)

[Lambdas Client Credentials JWT Populate Lambda Learn how to add custom claims to the access tokens FusionAuth issues for the Client Credentials grant. jwt populate lambdafusionauth lambdacustom claims](https://fusionauth.io/docs/lambdas/tokens/client-credentials-jwt-populate.md)

[Lambdas UserInfo Populate Lambda Learn how to add custom claims to the UserInfo response. fusionauth lambdacustom claimsopenid connect](https://fusionauth.io/docs/lambdas/tokens/userinfo-populate.md)

[Lambdas Login Validation Lambda Learn how to add your own validation to a login and reject logins that fail it. fusionauth lambdajavascript](https://fusionauth.io/docs/lambdas/login/login-validation.md)
---

## Other pages in Tokens

> For the full index of this section, see [Lambdas](https://fusionauth.io/docs/llms-lambdas.txt).

- [Client Credentials JWT Populate Lambda](https://fusionauth.io/docs/lambdas/tokens/client-credentials-jwt-populate.md): Learn how to add custom claims to the access tokens FusionAuth issues for the Client Credentials grant.
- [SAML v2 Populate Lambda](https://fusionauth.io/docs/lambdas/tokens/samlv2-response-populate.md): Learn how to customize the SAML v2 responses FusionAuth sends to service providers.
- [UserInfo Populate Lambda](https://fusionauth.io/docs/lambdas/tokens/userinfo-populate.md): Learn how to add custom claims to the UserInfo response.