Custom API routes

The built-in endpoints cover most cases. Replace them only when you need custom authentication or middleware: set enableEndpoints: false and build routes with the factories from @delmaredigital/payload-puck/api.

import { createPuckApiRoutesWithId } from '@delmaredigital/payload-puck/api'
import { getPayload } from 'payload'
import config from '@payload-config'

export const { GET, PATCH, DELETE } = createPuckApiRoutesWithId({
  collection: 'pages',
  payloadConfig: config,
  auth: {
    authenticate: async (request) => {
      const payload = await getPayload({ config })
      const { user } = await payload.auth({ headers: request.headers })
      if (!user) return { authenticated: false }
      return {
        authenticated: true,
        user: { ...user, id: String(user.id) },
        payloadUser: user,
      }
    },
    canDelete: async (user) => ({ allowed: user.role === 'admin' }),
  },
})

The factory returns both handlers. Mount GET at versions and POST at restore: the editor posts restores to the latter path.

export { POST } from '../versions/route'

The starter files include all four routes and a complete versions handler.

OptionsCopy Anchor Link

Auth hooksCopy Anchor Link

Each canX hook returns { allowed, error? }, synchronously or as a promise. Leaving one out adds no restriction beyond Payload's collection access.

Access controlCopy Anchor Link

authenticate and the canX hooks are authentication plus coarse route gating. They are not authorization; Payload's collection access rules are. Both layers apply.

The recommended wiring, for every auth systemCopy Anchor Link

Build authenticate on payload.auth(). It runs whatever auth strategies your Payload config registers (Better Auth, Clerk, custom strategies) and returns a real Payload user. Pass it unchanged as payloadUser for access checks. The separate user object is for route gating; its ID must be a string.

import type { PuckApiAuthHooks } from '@delmaredigital/payload-puck/api'
import { getPayload } from 'payload'
import config from '@payload-config'

export const auth: PuckApiAuthHooks = {
  authenticate: async (request) => {
    const payload = await getPayload({ config })
    const { user } = await payload.auth({ headers: request.headers })
    if (!user) return { authenticated: false }
    return {
      authenticated: true,
      user: { ...user, id: String(user.id) },
      payloadUser: user,
    }
  },
}

Callers with no Payload userCopy Anchor Link

Only if a caller genuinely has no corresponding Payload user, implement toPayloadUser. Whatever you return is the principal access control evaluates, so it must carry every field your access rules read. Return null to deliberately act as an anonymous request.

If authenticate already looked the Payload user up, return it as payloadUser and omit toPayloadUser to save the second lookup. The routes use toPayloadUser whenever it is defined, even if authenticate returned payloadUser. Otherwise they use payloadUser when it is not undefined (including null for anonymous access), then user if it is structurally a Payload user (it has a collection); otherwise they fail closed with PuckApiAccessError.

Behaviour to expectCopy Anchor Link

• Fails closed. If a route can't determine the Payload user, it returns 500 with code PUCK_ACCESS_MISCONFIGURED and performs no database operation. The server log carries the exact fix. It never silently downgrades to an anonymous request or skips authorization.
• Request headers reach your access rules. The routes forward the original request headers into every Payload operation, so an access rule that inspects them (an API-key scope check, for instance) sees the same request the REST API would. Each operation gets its own request object.
• Denials are 403. A Payload access denial used to surface as 500. These routes, and the built-in /api/puck/* endpoints, return the status Payload intended (403, 404, 409), so client error handling and monitoring can tell a denial from an outage.

Emergency opt-outCopy Anchor Link

Setting dangerouslyDisableCollectionAccessControl: true restores the old, vulnerable behaviour and logs a warning once per factory. It exists only as a rollback while you wire up toPayloadUser. With it set, your canX hooks are the only authorization in front of read, create, update, publish, delete and version restore.

Root props mappingCopy Anchor Link

Values edited in Puck's root fields are copied to Payload fields on save, and back into the editor on load, so they live in their own columns instead of only inside puckData. The defaults cover title, slug, the meta.* SEO fields, pageLayout and conversionTracking.*. In particular, metaTitle maps to meta.title and metaDescription to meta.description; you don't need custom mappings for these.

Custom mappings replace defaults with the same from value. Their to paths must exist on your pages collection. If you use custom routes alongside the admin editor, set the same rootPropsMapping on createPuckPlugin and the route factories: the admin editor loads with the plugin's mappings, while custom routes save with their own.

import { createPuckPlugin } from '@delmaredigital/payload-puck/plugin'
import { createPuckApiRoutesWithId } from '@delmaredigital/payload-puck/api'

// Optional example using a field the generated pages collection defines.
const rootPropsMapping = [
  { from: 'pageLayout', to: 'pageLayout' },
]

// In payload.config.ts:
createPuckPlugin({ rootPropsMapping })

// In your custom route, with config and auth as shown above.
// Both rootPropsMapping values must match for load/save parity.
export const { GET, PATCH, DELETE } = createPuckApiRoutesWithId({
  collection: 'pages',
  payloadConfig: config,
  auth,
  rootPropsMapping,
})