Token Data

During the lifecycle of a request you will be able to access the data you have configured to be stored in the JWT by accessing req.user. The user object is automatically appended to the request for you.

Defining Token Data

You can specify what data gets encoded to the Cookie/JWT-Token by setting saveToJWT property on fields within your auth collection.

1import type { CollectionConfig } from 'payload'
2
3export const Users: CollectionConfig = {
slug: 'users',
auth: true,
fields: [
  {
    // will be stored in the JWT
    saveToJWT: true,
    type: 'select',
    name: 'role',
    options: ['super-admin', 'user'],
  },
  {
    // the entire object will be stored in the JWT
    // tab fields can do the same thing!
    saveToJWT: true,
    type: 'group',
    name: 'group1',
    fields: [
      {
        type: 'text',
        name: 'includeField',
      },
      {
        // will be omitted from the JWT
        saveToJWT: false,
        type: 'text',
        name: 'omitField',
      },
    ],
  },
  {
    type: 'group',
    name: 'group2',
    fields: [
      {
        // will be stored in the JWT
        // but stored at the top level
        saveToJWT: true,
        type: 'text',
        name: 'includeField',
      },
      {
        type: 'text',
        name: 'omitField',
      },
    ],
  },
],
51}

Decoding a token produces the same flat token data shape used by earlier Payload versions:

1{
id: 'user-id',
collection: 'users',
email: 'user@example.com',
sid: 'session-id', // when sessions are enabled
role: 'super-admin', // fields configured with saveToJWT
iat: 1750000000,
exp: 1750007200,
9}

Payload reserves id, collection, email, sid, iat, and exp; fields configured with saveToJWT cannot replace these values. All other fields selected by saveToJWT, including fields that use a custom string key, are stored at the top level with the trusted authentication values.

Payload also signs authVersion: 1 into the token's protected JWT header. This marker identifies tokens issued by the fixed authentication format and is checked during authentication. It is not a decoded payload field, because an existing saveToJWT alias could use that name.

Using Token Data

This is especially helpful when writing Hooks and Access Control that depend on user defined fields.

1import type { CollectionConfig } from 'payload'
2
3export const Invoices: CollectionConfig = {
slug: 'invoices',
access: {
  read: ({ req, data }) => {
    if (!req?.user) return false
    if ({ req.user?.role === 'super-admin'}) {
      return true
    }
    return data.owner === req.user.id
  }
}
fields: [
  {
    name: 'owner',
    relationTo: 'users'
  },
  // ... other fields
],
21}

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Token Data

Defining Token Data

Using Token Data

Rotating your PAYLOAD_SECRET