obsidian/wiki/payloadcms/authentication-api-keys.md

title	aliases	tags	sources	created	updated
Authentication — API Keys	payload-api-keys payload-apikey-auth	payloadcms authentication api-keys rest-api access-control	raw/authentication__api-keys.md	2026-05-15	2026-05-15

Overview

API keys provide non-expiring authentication tokens generated per-user. Useful for third-party integrations and service accounts that need persistent access without repeated login flows.

Enabling API Keys

Set useAPIKey: true in the collection's auth config:

import type { CollectionConfig } from 'payload'

export const ThirdPartyAccess: CollectionConfig = {
  slug: 'third-party-access',
  auth: {
    useAPIKey: true,
  },
  fields: [],
}

Once enabled, the Admin Panel shows an API key generator UI per document in that collection.

HTTP Authentication

Set the Authorization header — format is {slug} API-Key {key}:

const response = await fetch('http://localhost:3000/api/pages', {
  headers: {
    Authorization: `users API-Key ${YOUR_API_KEY}`,
  },
})

• Header is case-sensitive
• Format: <collection-slug> API-Key <apiKey>
• Payload assigns the matched user to req.user and applies the same wiki/payloadcms/rest-api as email/password auth

API Key Only Auth

Disable email/password login entirely with disableLocalStrategy: true:

auth: {
  useAPIKey: true,
  disableLocalStrategy: true,
}

Useful for service accounts that should never authenticate via the admin panel.

Security

• API keys are encrypted at rest using PAYLOAD_SECRET
• If PAYLOAD_SECRET changes → all existing API keys become invalid and must be regenerated
• Treat API keys like passwords — rotate on suspected compromise

Patterns

Use case	Pattern
Third-party integration	Create dedicated user (e.g. dev@thirdparty.com), assign role, generate API key
Service account	disableLocalStrategy: true — API key only, no admin login
Per-service access control	Assign granular roles to the service user; same [[wiki/payloadcms/local-api

Key Takeaways

• useAPIKey: true on any auth-enabled collection enables per-user API key generation
• Authorization header format: {slug} API-Key {key} (case-sensitive)
• Keys are encrypted with PAYLOAD_SECRET — changing the secret invalidates all keys
• Use disableLocalStrategy: true to create pure API-key-only service accounts
• Access control is uniform — same rules apply regardless of auth method (API key vs email/password)
• Best practice: one API key user per external service, scoped to minimum required permissions

Sources

• raw/authentication__api-keys.md
• Official docs: https://payloadcms.com/docs/authentication/api-keys

Related

• wiki/payloadcms/rest-api — endpoint structure and query params
• wiki/payloadcms/local-api — server-side access bypassing HTTP auth
• wiki/payloadcms/admin-panel-overview — where API keys are generated in the UI