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}

The JWT keys id, collection, email, sid, iat, and exp are reserved for Payload. A custom string passed to saveToJWT cannot replace these keys.

Payload signs an authVersion: 1 marker in each token's protected JWT header. This identifies tokens issued by the fixed authentication format. Tokens issued before this protection was added do not have the marker and must be replaced by signing in again; integrations must also reissue stored bearer tokens. The decoded JWT payload remains flat and keeps fields configured with saveToJWT at the same paths, and /me returns the same data for a valid new token. The version marker is not a payload field.

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

Rich Text Editor