API Tokens#

API tokens allow external clients to authenticate requests to the Strapi Content API. For programmatic access to the Admin panel features, see Admin Tokens.

API tokens and Admin tokens are strictly separated: a Content API token is rejected on admin routes, and an admin token is rejected on Content API routes.

:::caution Security
Prefer read-only tokens for public access, scope tokens to only what you need, rotate long-lived tokens, and store them in a secrets manager.
:::

<ThemedImage
alt="API tokens"
sources={{
light: '/img/assets/settings/settings_pregen-api-tokens.png',
dark: '/img/assets/settings/settings_pregen-api-tokens_DARK.png',
}}
/>

Configuration#

Most configuration options for API tokens are available in the admin panel, and your Strapi project's code can be used to alter how API tokens are generated.

Admin panel settings#

Path to configure the feature: Settings > Global settings > API Tokens

The API Tokens interface displays a table listing all created content-api tokens.

From there, you have the possibility to:

• click on the to edit a token's name, description, type, duration or regenerate the token.
• click on the to delete a token.

Creating a new API token#

1. Click on the Create new API Token button.

2. In the API token edition interface, configure the new API token:

   Setting name	Instructions
   Name	Write the name of the API token.
   Description	(optional) Write a description for the API token.
   Token duration	Choose a token duration: 7 days, 30 days, 90 days, or Unlimited.
   Token type	Choose a token type: Read-only, Full access, or Custom.

3. (optional) For the Custom token type, define specific permissions for your API endpoints by clicking on the content-type name and using checkboxes to enable or disable permissions.

4. Click on the Save button. The new API token will be displayed at the top of the interface, along with a copy button .

<ThemedImage
alt="Custom API token"
sources={{
light: '/img/assets/settings/settings_api-token-custom.png',
dark: '/img/assets/settings/settings_api-token-custom_DARK.png',
}}
/>

:::info Viewable tokens
If an encryption key is configured in your Strapi project (admin.secrets.encryptionKey), the newly created and regenerated API tokens will be viewable at any time in the admin panel.

If no encryption key is set, tokens will only be viewable once, immediately after creation or regeneration.
:::

Regenerating an API token#

1. Click on the API token's edit button.
2. Click on the Regenerate button.
3. Click on the Regenerate button to confirm in the dialog.
4. Copy the new API token displayed at the top of the interface.

Code-based configuration#

New API tokens are generated using a salt. This salt is automatically generated by Strapi and stored in environment variables (the .env file) as API_TOKEN_SALT.

The salt can be customized:

• either by updating the string value for apiToken.salt in your /config/admin file
• or by creating an API_TOKEN_SALT environment variable in the .env file of the project

Changing the salt invalidates all the existing API tokens.

Ensuring API tokens are visible in the admin panel#

To allow persistent visibility of API tokens in the admin panel, an encryption key must be provided in your /config/admin file under secrets.encryptionKey:

module.exports = ({ env }) => ({
  // other config parameters
  secrets: {
    encryptionKey: env('ENCRYPTION_KEY'),
  }
});

export default ({ env }) => ({
  // other config parameters
  secrets: {
    encryptionKey: env('ENCRYPTION_KEY'),
  }
});

This key is used to encrypt and decrypt token values. Without this key, tokens remain usable, but will not be viewable after initial display. New Strapi projects will have this key automatically generated.

Usage#

Using API tokens allows executing a request on REST API or GraphQL API endpoints as an authenticated user.

API tokens can be helpful to give access to people or applications without managing a user account or changing anything in the Users & Permissions plugin.

When performing a request to Strapi's REST API, the API token should be added to the request's Authorization header with the following syntax: bearer your-api-token.