How to make right the per-user permission control for relationship-linked collections like UserSettings?

[MurzNN]

I need to store many different settings related to the user, like:

• Notification settings (enabled/disabled, enabled categories)
• Pinned items in the main menu
• Appearance settings
• etc

I think storing all these directly in the User collection is not good, because it will be loaded every time when I read the list of users, but this data is needed usually only for the currently logged-in user, not for others.

So, the first idea that came to mind is to create a separate collection UserSettings, and add a settings relationship field to the collection User - this looks good and convenient.

But I got stuck with the permission control for the UserSettings documents - how to restrict the read-write access to only the user to whom it relates?

I have no user id value or any other relation to a concrete user in the UserSettings collection, to add this to the beforeRead hook!

I can add a relationship field back to the user, but this will duplicate the information and make things more complex!

Also, I can add a "join" field that will provide a reference to the user, but the join field is mostly for one-to-many relationships, and will slow down loading the settings by an additional database join.

But I want to keep it as simple as possible!

So, asking for experience from the Payload community, how do you usually handle this? Please share your recommendations and the best approaches!

[MurzNN]

I found that Payload provides a local API to get and set the per-user preferences (getPreferences() and upsertPreferences()) but seems the performance of this feature is not good: it creates a separate document for each user preference, and loads it as a a separate database query.

So, for example, if we need to load the user, the appearance settings, notification settings, and the pinned items, there will be 4 separate database queries.

Also, reading these preferences does not seem to be available via the REST and GraphQL API, and it's not easy to update the preference of another user, because the function upsertPreferences() gets the user from the current request (req) and to update the preference of another user, we have to mock the request.

[KippieG]

The cleanest approach for per-user settings in Payload — without duplicating data or incurring expensive joins — is to store the relationship on the UserSettings document pointing back to the user, then use access control functions that check that field.

Recommended pattern

// collections/UserSettings.ts
import type { CollectionConfig } from 'payload'

export const UserSettings: CollectionConfig = {
  slug: 'user-settings',
  access: {
    create: ({ req }) => Boolean(req.user), // logged-in users only
    read: ({ req }) => {
      if (!req.user) return false
      // Only return docs where `owner` matches the logged-in user
      return {
        owner: { equals: req.user.id },
      }
    },
    update: ({ req }) => {
      if (!req.user) return false
      return {
        owner: { equals: req.user.id },
      }
    },
    delete: () => false, // or admin-only
  },
  fields: [
    {
      name: 'owner',
      type: 'relationship',
      relationTo: 'users',
      required: true,
      // Hide from admin UI list view if you want
      admin: { position: 'sidebar' },
    },
    {
      name: 'notifications',
      type: 'group',
      fields: [
        { name: 'enabled', type: 'checkbox', defaultValue: true },
        { name: 'categories', type: 'array', fields: [{ name: 'category', type: 'text' }] },
      ],
    },
    {
      name: 'pinnedItems',
      type: 'array',
      fields: [{ name: 'itemId', type: 'text' }],
    },
    {
      name: 'appearance',
      type: 'select',
      options: ['light', 'dark', 'system'],
      defaultValue: 'system',
    },
  ],
}

Why this works well

1. Access control returns a query constraint (not just true/false) — Payload automatically adds WHERE owner = :userId to all read/update queries. No beforeRead hook needed.

2. No data duplication — the owner field is a single FK. It's not duplicating the user record.

3. No join overhead on user lists — the UserSettings collection is completely separate. Loading the user list never touches this collection.

4. One-to-one via find on the frontend — to get the current user's settings:

   const settings = await payload.find({
     collection: 'user-settings',
     where: { owner: { equals: currentUserId } },
     limit: 1,
   })

On the User collection

You can optionally add a join field on the User collection as a convenience for the admin UI, but it's not required for the access control to work:

// In your Users collection fields:
{
  name: 'settings',
  type: 'join',
  collection: 'user-settings',
  on: 'owner',
  maxDepth: 0, // don't auto-populate in list queries
}

Setting maxDepth: 0 means it won't be fetched unless explicitly requested, keeping your user list queries fast.

Creating settings on user creation

Use an afterChange hook on the Users collection to auto-create a settings document:

afterChange: [
  async ({ doc, operation, req }) => {
    if (operation === 'create') {
      await req.payload.create({
        collection: 'user-settings',
        data: { owner: doc.id },
      })
    }
  },
],

This is the pattern most Payload apps use for per-user data — it's simple, performant, and Payload's access control constraint syntax handles all the security.