import AdminUrlCookiePath from '/docs/snippets/admin-url-cookie-path.md'

Admin panel configuration#

The /config/admin file is used to define the admin panel configuration for the Strapi application.

The present page acts as a reference for all the configuration parameters and values that you can find in the /config/admin file, grouped by topic. For additional information on how each feature works, please refer to links given in the introduction of each sub-section.

Admin panel behavior#

The admin panel behavior can be configured with the following parameters:

:::note config/admin vs. src/admin/app configurations
Some UI elements of the admin panel must be configured in the src/admin/app file:

Tutorial videos
To disable the information box containing the tutorial videos, set the config.tutorials key to false.

Releases notifications
To disable notifications about new Strapi releases, set the config.notifications.releases key to false.

const config = {
  // … other customization options go here
  tutorials: false,
  notifications: { releases: false },
};

export default {
  config,
};

:::

Admin panel server#

By default, Strapi's admin panel is exposed via http://localhost:1337/admin. For security reasons, the host, port, and path can be updated.

The server configuration for the admin panel can be configured with the following parameters:

Update the admin panel's path only#

To make the admin panel accessible at another path, for instance at http://localhost:1337/dashboard, define or update the url property:

module.exports = ({ env }) => ({
  // … other configuration properties
  url: "/dashboard",
});

Since by default the back-end server and the admin panel server run on the same host and port, only updating the config/admin file should work if you left the host and port property values untouched in the back-end server configuration file.

Update the admin panel's host and port#

If the admin panel server and the back-end server are not hosted on the same server, you will need to update the host and port of the admin panel. For example, to host the admin panel on my-host.com:3000:

module.exports = ({ env }) => ({
  host: "my-host.com",
  port: 3000,
  // Additionally you can define another path instead of the default /admin one 👇
  // url: '/dashboard' 
});

export default ({ env }) => ({
  host: "my-host.com",
  port: 3000,
  // Additionally you can define another path instead of the default /admin one 👇
  // url: '/dashboard'
});

Trust additional hosts during development#

When you run strapi develop, the admin panel is served through a Vite development server that Strapi boots in middleware mode and proxies through the Koa app. By default, Vite validates the Host header against a small set of safe values. Requests that do not match are rejected with an "Invalid Host" response, which prevents you from previewing the admin panel when it is reached through a tunnel, reverse proxy, or custom domain. Strapi exposes Vite's server.allowedHosts option so that you can extend that allowlist when necessary.

How Strapi loads custom Vite configuration#

During development Strapi builds a base Vite configuration, then tries to load a user-supplied config from ./src/admin/vite.config.{js,ts,mjs}. If the file exports a function it is invoked with the base configuration and Strapi uses the returned value. The project templates ship with an example file that simply merges a custom alias into the provided configuration, which is a good starting point for your own overrides.

Allow additional hosts#

Create ./src/admin/vite.config.ts (or .js) if it does not already exist and extend the dev-server configuration. The following example snippet adds 2 custom domains while keeping the rest of Strapi's defaults untouched:

import { mergeConfig } from 'vite';

export default (config) => {
  return mergeConfig(config, {
    server: {
      allowedHosts: ['preview.my-app.test', '.example-proxy.internal'],
    },
  });
};

import { mergeConfig, type UserConfig } from 'vite';

export default (config: UserConfig) => {
  return mergeConfig(config, {
    server: {
      allowedHosts: ['preview.my-app.test', '.example-proxy.internal'],
    },
  });
};

A few tips while configuring allowedHosts:

• Pass a string array or 'all', matching Vite's accepted shapes.
• Leading dots (.example.com) allow any subdomain.
• Combine this option with Strapi's existing hmr.clientPort setting when accessing the admin panel through tunnels that rewrite ports.

After saving the file, restart strapi develop. Vite will now trust requests whose Host header matches the entries you provided, so proxied or tunneled URLs will load without triggering host validation errors.

Deploy on different servers {#deploy-on-different-servers}#

Unless you chose to deploy Strapi's back-end server and admin panel server on different servers, by default:

• The back-end server and the admin panel server both run on the same host and port (http://localhost:1337/)
• The admin panel is accessible at the /admin path while the back-end server is accessible at the /api path

To deploy the admin panel and the back-end on completely different servers, you need to configure both the server (/config/server) and admin panel (/config/admin-panel) configurations.

The following example setup allows you to serve the admin panel from one domain while the API runs on another:

module.exports = ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

module.exports = ({ env }) => ({
  /**
   * Note: The administration will be accessible from the root of the domain 
   * (ex: http://yourfrontend.com/)
   */ 
  url: "/",
  serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files
});

export default ({ env }) => ({
  host: env("HOST", "0.0.0.0"),
  port: env.int("PORT", 1337),
  url: "http://yourbackend.com",
});

export default ({ env }) => ({
  /**
   * Note: The administration will be accessible from the root of the domain 
   * (ex: http://yourfrontend.com/)
   */ 
  url: "/",
  serveAdminPanel: false, // http://yourbackend.com will not serve any static admin files
});

With this configuration:

• The admin panel will be accessible at http://yourfrontend.com
• All API requests from the panel will be sent to http://yourbackend.com
• The backend server will not serve any static admin files due to serveAdminPanel: false

API tokens#

The API tokens feature can be configured with the following parameters:

Audit logs#

The Audit Logs feature can be configured with the following parameters:

:::note Retention days for self-hosted vs. Strapi Cloud users
For Strapi Cloud customers, the auditLogs.retentionDays value stored in the license information is used, unless a smaller retentionDays value is defined in the config/admin.js|ts configuration file.
:::

Authentication#

The authentication system, including SSO configuration and session management, can be configured with the following parameters:

Basic authentication#

To configure basic authentication, use the following parameters:

Additional configuration parameters are available for session management.

Session management#

Admin authentication uses session management by default for enhanced security.

Session management provides enhanced security for authentication in Strapi applications by using short-lived access tokens paired with longer-lived refresh tokens. This approach reduces the risk of token theft and allows for more granular control over user sessions.

:::caution Serve the admin panel over HTTPS
Since v5.24.0, Strapi stores admin authentication data in secure, HTTP-only cookies. Browsers only accept and send these cookies over HTTPS connections, so attempting to access the admin panel via plain HTTP prevents the session cookie from being set and results in failed logins. Always expose the admin panel through HTTPS in production (for example, by placing Strapi behind a TLS-terminating proxy or load balancer). Local development continues to work with the default configuration because cookies are not marked as secure in that environment.
:::

Strapi's session management system supports both admin panel authentication and Content API authentication through the Users & Permissions feature. The system provides:

:::tip New projects
Apps scaffolded with create-strapi-app have jwtManagement: 'refresh' and sessions.httpOnly: true set by default for the Users & Permissions feature in the generated config/plugins.* file. This enables refresh-token-based authentication with HTTP-only session cookies for Content API users out of the box.
:::

• Short-lived access tokens (typically 30 minutes) for API requests
• Refresh tokens for obtaining new access tokens
• Device-specific sessions for targeted logout
• Configurable token lifespans for different security requirements

To configure session lifespans and behavior, use the following parameters:

Cookie configuration#

To configure HTTP cookies for admin authentication, use the following parameters:

Content history#

The Content History feature can be configured with the following parameter:

:::note Retention days for Content History
The history.retentionDays value is only taken into account if it is smaller than the value stored in the license information. It cannot be used to keep history versions for longer than the license allows, and versions are never kept for more than 90 days.
:::

Feature flags#

The feature flags can be configured with the following parameters:

Forgot password#

The forgot password functionality, including email templating, can be configured with the following parameters:

Rate limiting#

The rate limiting for the admin panel's authentication endpoints can be configured with the following parameters. Additional configuration options come from the package:

Strapi AI {#strapi-ai}#

Strapi AI, adding features to the Content-Type Builder and Media Library with plans, can be enabled or disabled:

Transfer tokens#

Transfer tokens for the Data transfer feature can be configured with the following parameters:

Configuration examples#

The /config/admin file should at least include a minimal configuration with required parameters for authentication and API tokens. Additional parameters can be included for a full configuration.

The default configuration created with any new project should at least include the following:

module.exports = ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
  },
  auth: {
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});

export default ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
  },
   auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
  },
  auth: {
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});

module.exports = ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
    secrets: {
      encryptionKey: env('ENCRYPTION_KEY'),
    },
  },
  ai: {
    enabled: false, // use this to disable Strapi AI
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
    retentionDays: 120,
  },
  auth: {
    events: {
      onConnectionSuccess(e) {
        console.log(e.user, e.provider);
      },
      onConnectionError(e) {
        console.error(e.error, e.provider);
      },
    },
    options: {
      expiresIn: '7d',
    },
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
    sessions: {
      accessTokenLifespan: 1800, // 30 minutes
      maxRefreshTokenLifespan: 2592000, // 30 days
      idleRefreshTokenLifespan: 604800, // 7 days
      maxSessionLifespan: 604800, // 7 days
      idleSessionLifespan: 3600, // 1 hour
    },
    cookie: {
      domain: env('ADMIN_COOKIE_DOMAIN'),
      path: '/admin',
      sameSite: 'lax',
    },
  },
  history: { // only accessible with a Growth or Enterprise plan
    retentionDays: 30,
  },
  url: env('PUBLIC_ADMIN_URL', '/dashboard'),
  autoOpen: false,
  watchIgnoreFiles: [
    './my-custom-folder', // Folder
    './scripts/someScript.sh', // File
  ],
  host: 'localhost',
  port: 8003,
  serveAdminPanel: env.bool('SERVE_ADMIN', true),
  forgotPassword: {
    from: 'no-reply@example.com',
    replyTo: 'no-reply@example.com',
  },
  rateLimit: {
    interval: { hour: 1, min: 30 },
    timeWait: 3*1000,
    max: 10,
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});

export default ({ env }) => ({
  apiToken: {
    salt: env('API_TOKEN_SALT', 'someRandomLongString'),
    secrets: {
      encryptionKey: env('ENCRYPTION_KEY'),
    },
  },
  ai: {
    enabled: false, // use this to disable Strapi AI
  },
  auditLogs: { // only accessible with an Enterprise plan
    enabled: env.bool('AUDIT_LOGS_ENABLED', true),
    retentionDays: 120,
  },
  auth: {
    events: {
      onConnectionSuccess(e) {
        console.log(e.user, e.provider);
      },
      onConnectionError(e) {
        console.error(e.error, e.provider);
      },
    },
    options: {
      expiresIn: '7d',
    },
    secret: env('ADMIN_JWT_SECRET', 'someSecretKey'),
    sessions: {
      accessTokenLifespan: 1800, // 30 minutes
      maxRefreshTokenLifespan: 2592000, // 30 days
      idleRefreshTokenLifespan: 604800, // 7 days
      maxSessionLifespan: 604800, // 7 days
      idleSessionLifespan: 3600, // 1 hour
    },
    cookie: {
      domain: env('ADMIN_COOKIE_DOMAIN'),
      path: '/admin',
      sameSite: 'lax',
    },
  },
  history: { // only accessible with a Growth or Enterprise plan
    retentionDays: 30,
  },
  url: env('PUBLIC_ADMIN_URL', '/dashboard'),
  autoOpen: false,
  watchIgnoreFiles: [
    './my-custom-folder', // Folder
    './scripts/someScript.sh', // File
  ],
  host: 'localhost',
  port: 8003,
  serveAdminPanel: env.bool('SERVE_ADMIN', true),
  forgotPassword: {
    from: 'no-reply@example.com',
    replyTo: 'no-reply@example.com',
  },
  rateLimit: {
    interval: { hour: 1, min: 30 },
    timeWait: 3*1000,
    max: 10,
  },
  transfer: { 
    token: { 
      salt: env('TRANSFER_TOKEN_SALT', 'anotherRandomLongString'),
    } 
  },
});