## JWT claims configuration

JWT claims define the information included in your tokens. Frontegg's Token management allows you to customize which claims are included, ensuring your tokens contain exactly the information your application needs while maintaining security and compliance.

## Claim categories

### OIDC required claims

These claims are **mandatory** for OpenID Connect compliance and cannot be removed:

| Claim | Description | Example Value |
|  --- | --- | --- |
| `iss` | Issuer identifier | `"https://your-domain.frontegg.com"` |
| `sub` | Subject (unique user identifier) | `"user-123-456"` |
| `aud` | Audience (intended recipient) | `"your-client-id"` or `"your-app-id"` |
| `exp` | Expiration time (UNIX timestamp) | `1640995200` |
| `iat` | Issued at time (UNIX timestamp) | `1640991600` |


Audience claim flexibility
The `aud` claim can accept either `clientId` or `appId` as valid values, providing flexibility for different integration patterns.

br
OIDC claims are mandatory
These OIDC claims (`iss`, `sub`, `aud`, `exp`, `iat`) **must** be included in every token template. Removing them will cause token validation failures and break authentication flows.

### Frontegg required claims

These claims are **required** for proper Frontegg functionality:

| Claim | Description | Template Variable |
|  --- | --- | --- |
| `type` | Token type identifier | `"{{type}}"` |
| `tenantId` | Associated tenant ID | `"{{user.tenantId}}"` |


Claim name vs template variable
Note that the template variable `{{type}}` creates a claim named `type` in the JWT token.

Critical for Frontegg SDKs
The `type` and `tenantId` claims are **essential** for Frontegg SDKs to function properly. If these claims are missing from your JWT:

- **Frontend SDKs** will fail to identify the token type and tenant context
- **Backend SDKs** will not be able to validate tokens correctly
- **Authentication flows** may break entirely


**Always include these claims in your token templates.**

### User claims

Include user-specific information in your tokens:

| Claim | Description | Template Variable |
|  --- | --- | --- |
| `name` | User's display name | `"{{user.name}}"` |
| `email` | User's email address | `"{{user.email}}"` |
| `email_verified` | Email verification status | `"{{user.verified}}"` |
| `metadata` | Custom user metadata | `"{{user.metadata}}"` |
| `profilePictureUrl` | User's profile picture URL | `"{{user.profilePictureUrl}}"` |


### Entitlements claims

Include authorization information:

| Claim | Description | Template Variable |
|  --- | --- | --- |
| `roles` | User's assigned roles | `"{{user.tenant.roles}}"` |
| `permissions` | User's permissions | `"{{user.tenant.permissions}}"` |


Backend SDK authorization requirements
If you're using Frontegg **backend SDKs** for authorization checks, the `roles` and `permissions` claims are **critical**:

- Backend SDKs rely on these claims to perform role-based access control (RBAC)
- Missing `roles` or `permissions` claims will cause authorization checks to fail
- Users may be denied access to resources they should have access to


**Include `roles` and `permissions` claims if your backend uses Frontegg SDKs for authorization.**

### Account (tenant) claims

Include tenant-specific information:

| Claim | Description | Template Variable |
|  --- | --- | --- |
| `tenantIds` | All user's tenant IDs | `"{{user.tenantIds}}"` |


### Session claims

Include session-specific information:

| Claim | Description | Template Variable |
|  --- | --- | --- |
| `sid` | Session identifier | `"{{sid}}"` |
| `applicationId` | Application identifier | `"{{applicationId}}"` |


Claim name vs template variable
Note that the template variable `{{sid}}` creates a claim named `sid` in the JWT token.

## Configuring claims

Previous JWT configurations will be overridden
If you had previous configurations to modify JWT templates, they will be **overridden** once you create a template and use it in a targeting rule. The new template will replace any existing JWT customizations when applied through targeting rules.

### Adding claims

1. Navigate to your template's **Claims** tab
2. Select claims from the available categories
3. Use the template variables provided for each claim
4. Preview the resulting JWT structure


### Removing claims

1. Identify claims that are not needed for your use case
2. Remove them from your template (except required claims)
3. Ensure that your application can handle the reduced claim set


### Custom claim values

You can customize claim values using template variables:


```
{
  "custom_user_info": "{{user.name}} ({{user.email}})",
  "tenant_context": "{{user.tenantId}}",
  "user_metadata": "{{user.metadata}}"
}
```

## Claim validation and restrictions

### Internal claims protection

Frontegg protects certain internal claims that cannot be modified:

- `act` (Actor)
- `amr` (Authentication Methods References)
- `acr` (Authentication Context Class Reference)


br
Internal claim override
If you attempt to include internal Frontegg claims (`act`, `amr`, `acr`) in your template, they will be **automatically overridden** with Frontegg's internally generated values during token generation. Your custom values for these claims will be ignored.

### JWT prehook integration

Claims added via [JWT generation prehooks](/ciam/guides/integrations/prehooks#prehook-verdicts) will override template values:

- Prehook claims take precedence over template claims
- Use prehooks for dynamic claim generation
- Template claims provide the base structure


### Token size considerations

Keep token size manageable:

- **Header limits**: HTTP headers are typically limited to 8KB-16KB
- **Performance impact**: Larger tokens increase request/response times
- **Network overhead**: Consider bandwidth implications


**Optimization strategies:**

- Remove unnecessary claims
- Use shorter claim names where possible
- Consider claim value formats (arrays vs. strings)


## Example configurations

### Minimal security token

For high-security, short-lived tokens:


```
{
  "sub": "{{sub}}",
  "aud": "{{aud}}",
  "iss": "{{iss}}",
  "iat": {{iat}},
  "exp": {{exp}},
  "type": "{{type}}",
  "tenantId": "{{user.tenantId}}"
}
```

### Full-featured application token

For feature-rich applications:


```
{
  "sub": "{{sub}}",
  "name": "{{user.name}}",
  "email": "{{user.email}}",
  "email_verified": "{{user.verified}}",
  "roles": "{{user.tenant.roles}}",
  "permissions": "{{user.tenant.permissions}}",
  "tenantId": "{{user.tenantId}}",
  "aud": "{{aud}}",
  "iss": "{{iss}}",
  "iat": {{iat}},
  "exp": {{exp}},
  "type": "{{type}}"
}
```

### API integration token

For third-party API integrations:


```
{
  "sub": "{{sub}}",
  "email": "{{user.email}}",
  "tenantId": "{{user.tenantId}}",
  "permissions": "{{user.tenant.permissions}}",
  "aud": "{{aud}}",
  "iss": "{{iss}}",
  "iat": {{iat}},
  "exp": {{exp}},
  "type": "{{type}}"
}
```

Testing your claims
Ensure all required claims are present before saving your template. Templates cannot be saved without including the mandatory OIDC and Frontegg required claims.