diff --git a/docusaurus/docs/cms/configurations/admin-panel.md b/docusaurus/docs/cms/configurations/admin-panel.md index 3738dbf84b..f512d0215b 100644 --- a/docusaurus/docs/cms/configurations/admin-panel.md +++ b/docusaurus/docs/cms/configurations/admin-panel.md @@ -106,7 +106,7 @@ module.exports = ({ env }) => ({ -```js title="/config/admin.ts" +```ts title="/config/admin.ts" export default ({ env }) => ({ host: "my-host.com", port: 3000, @@ -208,7 +208,7 @@ module.exports = ({ env }) => ({ -```js title="/config/server.ts" +```ts title="/config/server.ts" export default ({ env }) => ({ host: env("HOST", "0.0.0.0"), port: env.int("PORT", 1337), @@ -216,7 +216,7 @@ export default ({ env }) => ({ }); ``` -```js title="/config/admin.ts" +```ts title="/config/admin.ts" export default ({ env }) => ({ /** * Note: The administration will be accessible from the root of the domain @@ -239,10 +239,14 @@ With this configuration: The [API tokens](/cms/features/api-tokens) feature can be configured with the following parameters: -| Parameter | Description | Type | Default | -|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------| -| `apiToken.salt` | Salt used to generate API tokens | string | Random string | -| `apiToken.secrets.encryptionKey` | Encryption key used to set API tokens visibility in the admin panel | string | Random string | +| Parameter | Description | Type | Default | +|------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|---------------| +| `apiToken.salt` | Salt used to generate API tokens (applies to both `content-api` and `admin` token kinds). | string | Random string | +| `apiToken.secrets.encryptionKey` | Encryption key used to set API token visibility in the admin panel. When set, token keys remain viewable at any time by the token's owner. | string | Random string | + +:::tip +Admin tokens — the new kind of API token for programmatic access to the Admin API — are configured entirely from the admin panel. No additional code-based configuration is required beyond the parameters above (see [Admin tokens](/cms/features/admin-tokens)). +::: ## Audit logs @@ -592,4 +596,4 @@ export default ({ env }) => ({ - \ No newline at end of file + diff --git a/docusaurus/docs/cms/features/admin-tokens.md b/docusaurus/docs/cms/features/admin-tokens.md new file mode 100644 index 0000000000..f52626f858 --- /dev/null +++ b/docusaurus/docs/cms/features/admin-tokens.md @@ -0,0 +1,125 @@ +--- +title: Admin Tokens +description: Learn how to use Admin tokens to authenticate programmatic access to the Strapi Admin API. +toc_max_heading_level: 4 +displayed_sidebar: cmsSidebar +tags: + - admin tokens + - admin panel + - authentication + - RBAC + - features +--- + +# Admin Tokens + + +Admin tokens authenticate programmatic access to the Strapi Admin API. Each token is scoped to a subset of its owner's permissions and is designed for automation workflows such as MCP agents, CI/CD pipelines, and scripts. + + +Admin tokens allow automated clients to authenticate requests to the Strapi Admin API. For authenticating requests to the Content API, see [API Tokens](/cms/features/api-tokens). + +Admin tokens and API tokens are strictly separated: each is rejected on the other's routes. + + + + Free feature + + + Minimum "Access the Admin tokens settings page" in Roles > Settings - Admin tokens + + + Available and activated by default + + + Available in both Development & Production environment + + + + + +## Configuration + +Admin tokens are configured entirely from the admin panel. No code-based configuration is specific to Admin tokens. The shared salt and encryption key that apply to all token kinds are set via `apiToken.salt` and `apiToken.secrets.encryptionKey` in your `/config/admin` file (see [API tokens](/cms/features/api-tokens#code-based-configuration)). + +**Path to configure the feature:** _Settings > Administration Panel > Admin Tokens_ + +### Creating a new Admin token + +1. Click on the **Add new Admin Token** button. +2. In the token creation form, configure the new Admin token: + + | Setting name | Instructions | + | --- | --- | + | Name | Write the name of the token. | + | Description | (optional) Write a description for the token. | + | Token duration | Choose a duration: _7 days_, _30 days_, _90 days_, or _Unlimited_. | +3. Define which admin actions this token can perform: + - Click the tabs below the form to browse permission categories. + - Use the checkboxes to enable or disable individual permissions. + + :::note + Permissions that the current user does not hold appear disabled and cannot be selected. Conditions applied to the owner's role are shown as read-only and apply automatically to the token. + ::: +4. Click on the **Save** button. The new Admin token will be displayed at the top of the interface, along with a copy button . + + + +:::caution +The plaintext token key is shown only once, immediately after creation or regeneration. The `admin.secrets.encryptionKey` configuration that makes Content API token keys persistently viewable does not apply to Admin tokens. Admin token keys are always restricted to the token owner, regardless of encryption configuration. +::: + +### Managing Admin tokens + +Admin tokens have a dedicated settings page at _Settings > Administration Panel > Admin Tokens_. The Admin Tokens page and the API Tokens page are independent interfaces, not filtered views of a shared list. + +The Admin Tokens page displays an **Owner** column showing the display name of each token's owner. + +A token can only be edited or deleted by its owner or a super-admin. + +When a super-admin views an Admin token owned by another user, a read-only **Owner** field appears in the token details panel. The permissions panel shows only the checkboxes within the token owner's permission scope, not the super-admin's unrestricted access. + +Removing a permission from a role causes admin tokens owned by users of that role to have the corresponding permission deleted automatically. + +:::caution Owner account deactivation and deletion + +* If the token owner's account is deleted, all Admin tokens owned by that user are automatically deleted along with their associated permissions. There is no recovery path. Rotate and replace Admin tokens before offboarding a team member who owns them. +* If the token owner's account is deactivated or blocked, any request authenticated with that owner's Admin token returns `401 Token owner is deactivated`. The token itself is not deleted. Re-activating or unblocking the owner restores token functionality. +::: + +#### Regenerating an Admin token + +The **Regenerate** button is only visible to the token's owner. Other users, including super-admins, do not see this button for tokens they do not own. + +To regenerate an Admin token: + +1. Click on the Admin 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 Admin token displayed at the top of the interface. + +## Usage + +Admin tokens authenticate requests to Strapi Admin API. Once you have [created and copied an Admin token](#creating-a-new-admin-token), add it to the `Authorization` header of your request using `Bearer` syntax: + +```bash title="Example: authenticated Admin API request" +curl -X GET \ + https://your-strapi-instance.com/admin/content-manager/collection-types/api::article.article \ + -H "Authorization: Bearer your-admin-token" +``` + +:::caution +Never expose Admin tokens in client-side code. Store them in a secrets manager or environment variable. +::: \ No newline at end of file diff --git a/docusaurus/docs/cms/features/api-tokens.md b/docusaurus/docs/cms/features/api-tokens.md index 8a5258ac99..aad4adbee9 100644 --- a/docusaurus/docs/cms/features/api-tokens.md +++ b/docusaurus/docs/cms/features/api-tokens.md @@ -1,6 +1,7 @@ --- title: API Tokens -description: Learn how you can use API tokens to manage end-users authentication. +description: Learn how to use content-api tokens to authenticate REST and GraphQL API requests in Strapi. +displayed_sidebar: cmsSidebar sidebar_position: 2 toc_max_heading_level: 5 tags: @@ -14,28 +15,27 @@ tags: # API Tokens -API tokens provide scoped authentication for REST and GraphQL requests without exposing user credentials. This documentation explains token types, creation, expiration, and secure usage within the admin panel. +API tokens authenticate external requests to the Strapi Content API without exposing user credentials. Each token is scoped to a set of permissions and expires after a configurable duration. -API tokens allow users to authenticate REST and GraphQL API queries (see [APIs introduction](/cms/api/content-api)). +API tokens allow external clients to authenticate requests to the Strapi [Content API](/cms/api/content-api). For programmatic access to the Admin API, see [Admin Tokens](/cms/features/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 server tokens to only what you need, rotate long‑lived tokens, and store them in a secrets manager. Never expose admin tokens in client‑side code. +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. ::: Free feature - - + Minimum "Access the API tokens settings page" in Roles > Settings - API tokens - Available by default - Available in both Development & Production environment @@ -57,12 +57,12 @@ Most configuration options for API tokens are available in the admin panel, and **Path to configure the feature:** _Settings > Global settings > API Tokens_ -The _API Tokens_ interface displays a table listing all of the created API tokens. More specifically, it displays each API token's name, description, date of creation, and date of last use. +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 an API token's name, description, type, duration or [regenerate the token](#regenerating-an-api-token). -- click on the to delete an API token. +- click on the to edit a token's name, description, type, duration or [regenerate the token](#regenerating-an-api-token). +- click on the to delete a token. :::note Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one. Since tokens can be only seen once without encryption configured, you may want to [regenerate](#regenerating-an-api-token) them after setting up an encryption key to make them permanently viewable. @@ -72,6 +72,7 @@ Strapi pre-generates 2 API tokens for you, a Full access one and a Read-only one 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. | @@ -135,7 +136,7 @@ module.exports = ({ env }) => ({ -```js title="/config/admin.ts" +```ts title="/config/admin.ts" export default ({ env }) => ({ // other config parameters secrets: { @@ -149,6 +150,10 @@ export default ({ env }) => ({ 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. +:::tip +For automation workflows that need to call the Admin API programmatically, use admin tokens instead. See [Admin Tokens](/cms/features/admin-tokens) for the full documentation. +::: + ## Usage Using API tokens allows executing a request on [REST API](/cms/api/rest) or [GraphQL API](/cms/api/graphql) endpoints as an authenticated user. diff --git a/docusaurus/docs/cms/features/rbac.md b/docusaurus/docs/cms/features/rbac.md index 4705e08da0..983c1cd396 100644 --- a/docusaurus/docs/cms/features/rbac.md +++ b/docusaurus/docs/cms/features/rbac.md @@ -156,13 +156,14 @@ Settings permissions can be configured for all settings accessible from *General | Email |
  • General
    • "Access the Email settings page" - gives access to Email settings
👉 Path reminder to Email settings:
*General > Settings > Users & Permissions plugin - Email templates* | | Media Library |
  • General
    • "Access the Media Library settings page" - gives access to Media Library settings
👉 Path reminder to Media Library settings:
*General > Settings > Global Settings - Media Library* | | Internationalization |
  • Locales
    • "Create" - allows to create new locales
    • "Read" - allows to see available locales
    • "Update" - allows to edit available locales
    • "Delete" - allows to delete locales
👉 Path reminder to the Internationalization settings:
*General > Settings > Global Settings - Internationalization* | -| Review Workflows |
  • "Create" - allows to create workflows
  • "Read" - allows to see created workflows
  • "Update" - allows to edit workflows
  • "Delete" - allows to delete workflows
👉 Path reminder to Review workflows settings:
*General > Settings > Global Settings - Review workflows* | -| Single sign on |
  • Options
    • "Read" - allows to access the SSO settings
    • "Update" - allows to edit the SSO settings
👉 Path reminder to the SSO settings:
*General > Settings > Global Settings - Single Sign-On* | +| Review Workflows |
  • "Create" - allows to create workflows
  • "Read" - allows to see created workflows
  • "Update" - allows to edit workflows
  • "Delete" - allows to delete workflows
👉 Path reminder to Review workflows settings:
*General > Settings > Global Settings - Review workflows* | +| Single sign on |
  • Options
    • "Read" - allows to access the SSO settings
    • "Update" - allows to edit the SSO settings
👉 Path reminder to the SSO settings:
*General > Settings > Global Settings - Single Sign-On* | | Audit Logs |
  • Options
    • "Read" - allows to access the Audit Logs settings
👉 Path reminder to the Audit Logs settings:
*General > Settings > Admin Panel - Audit Logs* | | Plugins and Marketplace |
  • Marketplace
    • "Access the Marketplace" - gives access to the Marketplace
| | Webhooks |
  • General
    • "Create" - allows to create webhooks
    • "Read" - allows to see created webhooks
    • "Update" - allows to edit webhooks
    • "Delete" - allows to delete webhooks
👉 Path reminder to Webhook settings:
*General > Settings > Global Settings - Webhook* | | Users and Roles |
  • Users
    • "Create (invite)" - allows to create administrator accounts
    • "Read" - allows to see existing administrator accounts
    • "Update" - allows to edit administrator accounts
    • "Delete" - allows to delete administrator accounts
  • Roles
    • "Create" - allows to create administrator roles
    • "Read" - allows to see created administrator roles
    • "Update" - allows to edit administrator roles
    • "Delete" - allows to delete administrator roles
👉 Path reminder to the RBAC feature:
*General > Settings > Administration Panel* | | API Tokens |
  • API tokens
    • "Access the API tokens settings page" - toggles access to the API tokens page
  • General
    • "Create (generate)" - allows the creation of API tokens
    • "Read" - allows you to see created API tokens (disabling this permission will disable access to the *Global Settings - API Tokens* settings)
    • "Update" - allows editing of API tokens
    • "Delete (revoke)" - allows deletion of API tokens
    • "Regenerate" - allows regeneration of the API token
👉 Path reminder to API Tokens settings:
*General > Settings > Global Settings - API Tokens* | +| Admin Tokens |
  • Admin tokens
    • "Access the Admin tokens settings page" - toggles access to the Admin Tokens page
  • General
    • "Create (generate)" - allows the creation of Admin tokens
    • "Read" - allows you to see created Admin tokens
    • "Update" - allows editing of Admin tokens
    • "Delete (revoke)" - allows deletion of Admin tokens
    • "Regenerate" - allows regeneration of Admin tokens
👉 Path reminder to Admin Tokens settings:
*General > Settings > Administration Panel - Admin Tokens* | | Project |
  • General
    • "Update the project level settings" - allows to edit the settings of the project
    • "Read the project level settings" - gives access to settings of the project
| | Transfer Tokens |
  • Transfer tokens
    • "Access the Transfer tokens settings page" - toggles access to the Transfer tokens page
  • General
    • "Create (generate)" - allows the creation of Transfer tokens
    • "Read" - allows you to see created Transfer tokens (disabling this permission will disable access to the *Global Settings - Transfer Tokens* settings)
    • "Update" - allows editing of Transfer tokens
    • "Delete (revoke)" - allows deletion of Transfer tokens
    • "Regenerate" - allows regeneration of the Transfer token
👉 Path reminder to Transfer Tokens settings:
*General > Settings > Global Settings - Transfer Tokens* | diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index d56cc90c9f..dceb61b2f0 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -60,6 +60,7 @@ const sidebars = { label: 'API Tokens', id: 'cms/features/api-tokens', }, + 'cms/features/admin-tokens', { type: 'doc', label: 'Audit Logs', diff --git a/docusaurus/static/img/assets/settings/settings_admin-token-creation.png b/docusaurus/static/img/assets/settings/settings_admin-token-creation.png new file mode 100644 index 0000000000..5fca48d871 Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings_admin-token-creation.png differ diff --git a/docusaurus/static/img/assets/settings/settings_admin-token-creation_DARK.png b/docusaurus/static/img/assets/settings/settings_admin-token-creation_DARK.png new file mode 100644 index 0000000000..a707af204c Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings_admin-token-creation_DARK.png differ diff --git a/docusaurus/static/img/assets/settings/settings_admin-tokens-overview.png b/docusaurus/static/img/assets/settings/settings_admin-tokens-overview.png new file mode 100644 index 0000000000..3dda3c7135 Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings_admin-tokens-overview.png differ diff --git a/docusaurus/static/img/assets/settings/settings_admin-tokens-overview_DARK.png b/docusaurus/static/img/assets/settings/settings_admin-tokens-overview_DARK.png new file mode 100644 index 0000000000..dc34b7dbed Binary files /dev/null and b/docusaurus/static/img/assets/settings/settings_admin-tokens-overview_DARK.png differ