obsidian/wiki/payloadcms/authentication-token-data.md

title	aliases	tags	sources	created	updated
Authentication — Token Data (saveToJWT)	token-data jwt-token-data saveToJWT	payloadcms authentication jwt access-control	raw/authentication__token-data.md	2026-05-15	2026-05-15

Overview

Payload lets you embed any field value into the Cookie/JWT so it's available on every request via req.user — without an extra DB lookup.

Defining Token Data

Add saveToJWT: true to any field in an auth collection:

export const Users: CollectionConfig = {
  slug: 'users',
  auth: true,
  fields: [
    {
      saveToJWT: true,       // stored in JWT at key "role"
      type: 'select',
      name: 'role',
      options: ['super-admin', 'user'],
    },
  ],
}

Group / Tab Fields

Config	Result
saveToJWT: true on the group	Entire group object stored under its name key
saveToJWT: true on a field inside a group	That field hoisted to top level of JWT
saveToJWT: false on a field inside a saveToJWT: true group	Field omitted from JWT

Custom Key

Pass a string instead of true to store the value under a different key:

{ saveToJWT: 'userRole', name: 'role', type: 'select', ... }
// → req.user.userRole

Using Token Data

req.user is populated automatically on every authenticated request:

export 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
    },
  },
  // ...
}

Useful in wiki/payloadcms/authentication-overview and wiki/payloadcms/authentication-operations wherever you need role/tenant/group info without hitting the DB.

Key Takeaways

• saveToJWT: true on a field → value baked into every JWT/cookie issued at login
• Group-level saveToJWT: true → stores the whole group object; field-level inside a group → hoists to top level
• saveToJWT: false on a child field overrides parent group's saveToJWT: true
• saveToJWT: "customKey" stores data under that key instead of the field name
• Access via req.user.<fieldName> in any hook or access-control function — no extra DB query needed
• Re-login required after changing saveToJWT fields; existing tokens won't have the new data

Related

• wiki/payloadcms/authentication-overview — enable auth, all config options
• wiki/payloadcms/authentication-jwt — Authorization header flow, token validation
• wiki/payloadcms/authentication-custom-strategies — replace built-in auth entirely
• wiki/payloadcms/authentication-operations — login, refresh, me endpoints

Sources

• raw/authentication__token-data.md
• https://payloadcms.com/docs/authentication/token-data