---
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