---
title: "JWT Authentication Details"
slug: "jwt-authentication-details"
updated: 2026-07-03T10:16:08Z
published: 2026-07-03T10:16:08Z
canonical: "docs.xtremepush.com/jwt-authentication-details"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xtremepush.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JWT Authentication Details

Configure a JWT secret and learn the required payload formats for authenticating users in your game.

## Use JWT authentication

To use a JWT for your game's authentication:

1. Go to the **Configuration** tab of your game.
2. In the **JWT Auth Secret** field, either:
  - Click the refresh icon to generate a secure key (recommended).
  - Enter a UTF8 key directly to provide your own secret key. The key must be at least 32 characters long (256 bit).
3. Save your settings.

Your system uses this secret key to sign the JWT token's signature using the HS256 algorithm. Xtremepush uses the same secret to verify the token's authenticity.

## Required JWT format

The JWT payload must follow a specific structure for Xtremepush to identify the user and validate the token. The required structure depends on whether your user data is managed in Xtremepush or externally.

### User data managed in Xtremepush

When Xtremepush manages user data, use the following JWT payload structure:

```json
{
  "account": "34523453",
  "expiration": "2024-12-18T15:31:00.983Z"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `account` | Yes | The unique user ID of the logged-in user for whom the game is being launched. The value must be a string. |
| `expiration` | No | The token's validity period. The value must be in ISO 8601 format. |

### User data not managed in Xtremepush

When user data is not managed in Xtremepush, use the following JWT payload structure:

```json
{
  "account": "34523453",
  "metadata": {
    "custom_attribute1": 123,
    "custom_attribute2": 233
  },
  "expiration": "2025-09-15T10:00:00Z"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `account` | Yes | The unique user ID of the logged-in user. The value must be a string. |
| `metadata` | Yes | The custom attributes and their corresponding values created for your user segments. See [Before you create a game campaign](/documentation/docs/before-you-create-a-game-campaign) for more information. |
| `expiration` | No | The token's validity period. The value must be in ISO 8601 format. |