API Key Strategy

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.
2. Generate a non-expiring API key for that user to request with.

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. The Admin Panel then allows users who are granted admin access to generate, regenerate, or revoke keys. All other users are denied by default.

By default, no users can read generated API keys through Payload's built-in read operations, including admins. See Revealing API keys for more details.

Payload displays a generated API key only once. Copy it when it is generated. Payload omits the key from all reads and displays only a masked value after it is saved.

An API key is independent of the user's password. Changing or resetting a password does not disable an existing API key, so remove or regenerate the key when its access should end.

Restricting API key management

By default, only users who are granted admin access can manage API keys. You can further restrict generation, regeneration, and revocation by overriding the generated apiKey field's create and update access. See Fields Generated by Payload for a complete example.

Revealing API keys

By default, API keys are hidden after generation. To allow users who are granted admin access to reveal stored keys, set auth.useAPIKey.reveal to true:

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. By doing this, Payload recognizes the request being made as a request by the user associated with that API key.

For example, using Fetch:

Payload ensures that the same, uniform Access Control 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.