5e4e27460e
### What? This PR fixes numerous links across the docs, both internal docs links and external links. This PR also fixes some minor formatting issues in some places, as well as optically aligns the markdown tables in tables that had broken links. ### Why? To properly link readers to the correct location in the docs, and for better formatting and easier consumption. ### How? Changes to many `.mdx` files in the `docs` folder. Notes: - There are duplicative section id's in `docs/authentication/email.mdx`, I've fixed one such link, but have left it as is for now.
82 lines
4.0 KiB
Plaintext
82 lines
4.0 KiB
Plaintext
---
|
|
title: API Key Strategy
|
|
label: API Key Strategy
|
|
order: 50
|
|
desc: Enable API key based authentication to interface with Payload.
|
|
keywords: authentication, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
To integrate with third-party APIs or services, you might need the ability to generate API keys that can be used to identify as a certain user within Payload. API keys are generated on a user-by-user basis, similar to email and passwords, and are meant to represent a single user.
|
|
|
|
For example, if you have a third-party service or external app that needs to be able to perform protected actions against Payload, first you need to create a user within Payload, i.e. `dev@thirdparty.com`. From your external application you will need to authenticate with that user, you have two options:
|
|
|
|
1. Log in each time with that user and receive an expiring token to request with.
|
|
1. Generate a non-expiring API key for that user to request with.
|
|
|
|
<Banner type="success">
|
|
**Tip:**
|
|
|
|
This is particularly useful as you can create a "user" that reflects an integration with a specific external service and assign a "role" or specific access only needed by that service/integration.
|
|
</Banner>
|
|
|
|
Technically, both of these options will work for third-party integrations but the second option with API key is simpler, because it reduces the amount of work that your integrations need to do to be authenticated properly.
|
|
|
|
To enable API keys on a collection, set the `useAPIKey` auth option to `true`. From there, a new interface will appear in the [Admin Panel](../admin/overview) for each document within the collection that allows you to generate an API key for each user in the Collection.
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const ThirdPartyAccess: CollectionConfig = {
|
|
slug: 'third-party-access',
|
|
auth: {
|
|
useAPIKey: true, // highlight-line
|
|
},
|
|
fields: [],
|
|
}
|
|
```
|
|
|
|
User API keys are encrypted within the database, meaning that if your database is compromised,
|
|
your API keys will not be.
|
|
|
|
<Banner type="warning">
|
|
**Important:**
|
|
If you change your `PAYLOAD_SECRET`, you will need to regenerate your API keys.
|
|
|
|
The secret key is used to encrypt the API keys, so if you change the secret, existing API keys will
|
|
no longer be valid.
|
|
</Banner>
|
|
|
|
### HTTP Authentication
|
|
|
|
To authenticate REST or GraphQL API requests using an API key, set the `Authorization` header. The header is case-sensitive and needs the slug of the `auth.useAPIKey` enabled collection, then " API-Key ", followed by the `apiKey` that has been assigned. Payload's built-in middleware will then assign the user document to `req.user` and handle requests with the proper [Access Control](../access-control/overview). By doing this, Payload recognizes the request being made as a request by the user associated with that API key.
|
|
|
|
**For example, using Fetch:**
|
|
|
|
```ts
|
|
import Users from '../collections/Users'
|
|
|
|
const response = await fetch('http://localhost:3000/api/pages', {
|
|
headers: {
|
|
Authorization: `${Users.slug} API-Key ${YOUR_API_KEY}`,
|
|
},
|
|
})
|
|
```
|
|
|
|
Payload ensures that the same, uniform [Access Control](../access-control/overview) is used across all authentication strategies. This enables you to utilize your existing Access Control configurations with both API keys and the standard email/password authentication. This consistency can aid in maintaining granular control over your API keys.
|
|
|
|
### API Key Only Auth
|
|
|
|
If you want to use API keys as the only authentication method for a collection, you can disable the default local strategy by setting `disableLocalStrategy` to `true` on the collection's `auth` property. This will disable the ability to authenticate with email and password, and will only allow for authentication via API key.
|
|
|
|
```ts
|
|
import type { CollectionConfig } from 'payload'
|
|
|
|
export const ThirdPartyAccess: CollectionConfig = {
|
|
slug: 'third-party-access',
|
|
auth: {
|
|
useAPIKey: true,
|
|
disableLocalStrategy: true, // highlight-line
|
|
},
|
|
}
|
|
```
|