93 lines
3 KiB
Markdown
93 lines
3 KiB
Markdown
---
|
|
title: "Authentication — API Keys"
|
|
aliases: [payload-api-keys, payload-apikey-auth]
|
|
tags: [payloadcms, authentication, api-keys, rest-api, access-control]
|
|
sources: [raw/authentication__api-keys.md]
|
|
created: 2026-05-15
|
|
updated: 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:
|
|
|
|
```ts
|
|
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}`:
|
|
|
|
```ts
|
|
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|Access Control]] as email/password auth
|
|
|
|
## API Key Only Auth
|
|
|
|
Disable email/password login entirely with `disableLocalStrategy: true`:
|
|
|
|
```ts
|
|
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|Access Control]] applies |
|
|
|
|
## 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|REST API]] — endpoint structure and query params
|
|
- [[wiki/payloadcms/local-api|Local API]] — server-side access bypassing HTTP auth
|
|
- [[wiki/payloadcms/admin-panel-overview|Admin Panel Overview]] — where API keys are generated in the UI
|