authentik/website/docs/install-config/configuration/configuration.mdx

---
title: Configuration
---

This page details all the authentik configuration options that you can set via environment variables.

## About authentik configurations

:::info
The double-underscores are intentional, as all these settings are translated to YAML internally, and a double-underscore indicates the next level (a subsetting).
:::

All of these variables can be set to values, but you can also use a URI-like format to load values from other places:

- `env://<name>` Loads the value from the environment variable `<name>`. Fallback can be optionally set like `env://<name>?<default>`
- `file://<name>` Loads the value from the file `<name>`. Fallback can be optionally set like `file://<name>?<default>`

## Set your environment variables

import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";

<Tabs groupId="platform">
  <TabItem value="docker-compose" label="Docker Compose" default>
    If you are using Docker Compose, edit your <code>.env</code> file to append any keys that you want to add, and then run the following command to apply them:

    ```
    docker compose up -d
    ```

  </TabItem>
  <TabItem value="kubernetes" label="Kubernetes">
    If you are running in Kubernetes, edit your <code>values.yaml</code> file to append any keys that you want to add, and then run the following commands to apply:

    ```
    helm repo update
    helm upgrade --install authentik authentik/authentik -f values.yaml
    ```

  </TabItem>

</Tabs>

## Verify your configuration settings

To check if your config has been applied correctly, you can run the following command to output the full config:

<Tabs groupId="platform">
  <TabItem value="docker-compose" label="Docker Compose" default>

    ```
    docker compose run --rm worker ak dump_config
    ```

  </TabItem>
  <TabItem value="kubernetes" label="Kubernetes">

    ```
    kubectl exec -it deployment/authentik-worker -c worker -- ak dump_config
    ```

  </TabItem>

</Tabs>

## PostgreSQL settings

authentik requires PostgreSQL for application data, configuration, sessions, and background task coordination. authentik supports PostgreSQL 14 - 18.

The database should use the `UTF8` encoding, which is PostgreSQL's default. Unless a different encoding was explicitly chosen when the database was created, no change is needed. Run `SHOW server_encoding;` to check; authentik logs a warning on any other encoding, and support for them will be removed in an upcoming version. Converting an existing database means dumping it, re-creating it with `ENCODING 'UTF8'`, and restoring the dump.

Use the settings in this section to configure:

- the primary PostgreSQL connection
- TLS/SSL settings for PostgreSQL
- connection behavior and pooler compatibility
- optional read replicas

For more information, see the PostgreSQL upgrade guides for [Docker Compose](../../troubleshooting/postgres/upgrade_docker.mdx) and [Kubernetes](../../troubleshooting/postgres/upgrade_kubernetes.mdx). For backup guidance, see [Backup and restore](../../sys-mgmt/ops/backup-restore.mdx).

### Connection settings

These settings define the primary database connection used for writes and reads, unless you've set up read replicas.

- `AUTHENTIK_POSTGRESQL__HOST`

    Hostname or IP address of the PostgreSQL server.

- `AUTHENTIK_POSTGRESQL__PORT`

    Port on which PostgreSQL is listening.

    Default: `5432`

- `AUTHENTIK_POSTGRESQL__USER`

    PostgreSQL username used by authentik to authenticate.

- `AUTHENTIK_POSTGRESQL__PASSWORD`

    PostgreSQL password used by authentik to authenticate.

    If unset, authentik falls back to `POSTGRES_PASSWORD`. This fallback exists for the default Docker Compose setup and should not be relied on in more complex deployments.

- `AUTHENTIK_POSTGRESQL__NAME`

    Name of the PostgreSQL database to use.

:::info Hot-reloading
The `AUTHENTIK_POSTGRESQL__HOST`, `AUTHENTIK_POSTGRESQL__PORT`, `AUTHENTIK_POSTGRESQL__USER`, and `AUTHENTIK_POSTGRESQL__PASSWORD` settings support hot-reloading and can be changed without restarting authentik. However, adding or removing read replicas requires a restart.
:::

### TLS/SSL settings

Use these settings when your PostgreSQL server requires TLS/SSL or mutual TLS.

- `AUTHENTIK_POSTGRESQL__SSLMODE`

    Controls how TLS/SSL is used and verified for PostgreSQL connections.

    Default: `verify-ca`
    - `disable`: No SSL is used.
    - `allow`: Use SSL if available, but don't perform verification.
    - `prefer`: Attempt an SSL connection first, fall back to non-SSL if it fails.
    - `require`: Require an SSL connection, but without certificate verification.
    - `verify-ca`: Require SSL and verify that the server certificate is signed by a trusted CA.
    - `verify-full`: Require SSL, verify the CA, and verify that the server hostname matches the certificate.

- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`

    Path to the CA certificate file used to verify the PostgreSQL server certificate.

    Required for `verify-ca` and `verify-full` modes.

- `AUTHENTIK_POSTGRESQL__SSLCERT`

    Path to the client certificate file.

    Required only if PostgreSQL is configured for mutual TLS and requires client certificates.

- `AUTHENTIK_POSTGRESQL__SSLKEY`

    Path to the private key corresponding to `AUTHENTIK_POSTGRESQL__SSLCERT`.

For more detail, see [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) and the [PostgreSQL `libpq` SSL documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION).

### Connection management

These settings control connection persistence and behavior, which is particularly important when using a connection pooler like PgBouncer or Pgpool.

- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`

    Maximum age of a database connection in seconds.
    - `0` (default): Connections are closed after each request.
    - greater than `0`: Enables persistent connections, with the value defining the maximum lifetime.
    - `None`: Unlimited persistence. Use with caution, especially with connection poolers.

    In session pool mode, if the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected. See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections).

- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`

    Enables health checks on persistent connections before reuse.

    Default: `false`

    This helps avoid errors caused by stale connections that were closed by PostgreSQL, a proxy, or a connection pooler. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks).

- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`

    Disables server-side cursors.

    Default: `false`

    Set this to `true` when using transaction-based pooling, or when you encounter cursor-related errors behind a pooler. Server-side cursors maintain state across queries and are not compatible with transaction pooling. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors).

### Advanced Settings

- `AUTHENTIK_POSTGRESQL__DEFAULT_SCHEMA`

    The name of the database schema for authentik to use. Defaults to `public`.

    This can only be set before authentik starts for the first time. If you use a custom schema:
    - the schema must already exist
    - the PostgreSQL user must have permission to use it
    - the user's `search_path` must include that schema

- `AUTHENTIK_POSTGRESQL__CONN_OPTIONS`

    :::info Deprecated
    Deprecated as of version 2026.5 and will be removed in a future version. If you rely on a specific parameter, open an issue so we can discuss an alternative.
    :::

    Additional `libpq` connection parameters for the primary database connection.

    A list of supported parameter keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
    - Parameters passed with this setting will override those passed with other settings.
    - These parameters are not applied to read replicas.
    - The value must be a base64-encoded JSON dictionary.

### Read replicas

You can configure additional read replica databases to distribute database load and improve performance. When read replicas are configured, authentik automatically routes query operations between the primary database (for writes) and read replica databases (for queries).

By default, the primary database won't be used for queries when read replicas are available. If you want the primary database to also handle queries, add it as a read replica.

Each replica uses the same setting structure as the primary connection, but under `READ_REPLICAS`.

For the first replica, use index `0`:

- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__USER`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PORT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__PASSWORD`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLMODE`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLROOTCERT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLCERT`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__SSLKEY`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_MAX_AGE`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_HEALTH_CHECKS`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__DISABLE_SERVER_SIDE_CURSORS`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_OPTIONS` (deprecated, see above)

Use index `1`, `2`, and so on for additional replicas.

- `AUTHENTIK_POSTGRESQL__REPLICA_CONN_OPTIONS`

    :::info Deprecated
    Deprecated as of version 2026.5 and will be removed in a future version. If you rely on a specific parameter, open an issue so we can discuss an alternative.
    :::

    Additional `libpq` connection parameters for all read replica connections.

    A list of supported keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
    - Parameters passed with this setting will override those passed with other settings.
    - The value must be a base64-encoded JSON dictionary.

### Use a PostgreSQL connection pooler {#using-a-postgresql-connection-pooler}

If authentik connects through a pooler such as PgBouncer or Pgpool, review these settings carefully:

- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`

    Session-based pooling can behave poorly with unlimited persistent connections (`null`). If the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected.

    To avoid this, either:
    - use transaction pooling, or
    - set `CONN_MAX_AGE` lower than the timeout that causes backend connections to be dropped, including `0` to disable persistent connections

- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`

    When using transaction pooling, set this to `true`. Server-side cursors keep state across queries and will break when subsequent queries are sent over different backend connections.

#### Session-scoped operations and transaction-mode poolers

Some authentik subsystems need to keep state alive on a single PostgreSQL backend connection across multiple statements:

- The Django Channels Postgres layer issues `LISTEN channels_messages` on a long-lived connection.
- The dramatiq worker issues `LISTEN authentik.tasks.<queue>.enqueue` and uses session-scoped `pg_advisory_lock(<message-lock-id>)` / `pg_advisory_unlock(<message-lock-id>)` to coordinate message consumption.
- The startup migration script holds `pg_advisory_lock(1000)` across the entire migrate + system-check pass.

A transaction-pooling pooler (PgBouncer in `pool_mode = transaction`, Cloud SQL's managed connection pooling, etc.) returns the backend to the pool at every `COMMIT`, which breaks all of the above. The pooler may also rewrite which physical backend handles the next statement, so the registered `LISTEN` channel disappears and any session-scoped advisory locks become unreachable.

To run the bulk of ORM traffic through a transaction-pooling pooler while keeping the LISTEN/NOTIFY and advisory-lock paths working, configure a second endpoint that points either directly at PostgreSQL or at a session-mode pooler:

- `AUTHENTIK_POSTGRESQL__DIRECT__HOST`
- `AUTHENTIK_POSTGRESQL__DIRECT__PORT`
- `AUTHENTIK_POSTGRESQL__DIRECT__NAME`
- `AUTHENTIK_POSTGRESQL__DIRECT__USER`
- `AUTHENTIK_POSTGRESQL__DIRECT__PASSWORD`
- `AUTHENTIK_POSTGRESQL__DIRECT__SSLMODE`
- `AUTHENTIK_POSTGRESQL__DIRECT__SSLROOTCERT`
- `AUTHENTIK_POSTGRESQL__DIRECT__SSLCERT`
- `AUTHENTIK_POSTGRESQL__DIRECT__SSLKEY`
- `AUTHENTIK_POSTGRESQL__DIRECT__CONN_OPTIONS` (deprecated, see above)

Any setting left unset falls back to the corresponding top-level `AUTHENTIK_POSTGRESQL__*` value, so the common case of "same database, different endpoint" only requires `AUTHENTIK_POSTGRESQL__DIRECT__HOST` (and optionally `AUTHENTIK_POSTGRESQL__DIRECT__PORT`).

When any of these are set, authentik:

- Adds a Django database alias named `direct` that points at this endpoint. The alias is automatically excluded from the read-replica pool and from migrations — the underlying database is migrated through the `default` endpoint.
- Routes the Channels Postgres layer's connection pool and its LISTEN connection through the `direct` alias.
- Routes the dramatiq worker's `_listen_connection` and `_locks_connection` through the `direct` alias. The main task-table ORM queries (enqueue, status updates) continue to use the `default` alias.
- Opens the startup migration advisory-lock connection against the direct endpoint.

If `AUTHENTIK_POSTGRESQL__DIRECT__*` is not set, all of these connections share the same endpoint as the rest of ORM traffic, and putting a transaction-pool pooler in front of `AUTHENTIK_POSTGRESQL__HOST` will silently break LISTEN/NOTIFY and the dramatiq advisory locks.

### Recommended starting points

These are good starting points for common deployments:

- Direct PostgreSQL connection:
    - leave `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE` as `0`
    - leave `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS` as `false`
- PgBouncer or Pgpool in transaction mode:
    - set `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS=true`
    - keep `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE=0` unless you have a reason to change it
    - configure `AUTHENTIK_POSTGRESQL__DIRECT__HOST` (and `AUTHENTIK_POSTGRESQL__DIRECT__PORT` if needed) to point either directly at PostgreSQL or at a session-mode pooler endpoint, so the channel layer, worker LISTEN connection, and migration advisory lock keep working
- Cloud SQL with managed connection pooling:
    - the managed pooler is PgBouncer in transaction mode, so all of the above applies
    - point `AUTHENTIK_POSTGRESQL__HOST` at the pooled endpoint
    - point `AUTHENTIK_POSTGRESQL__DIRECT__HOST` at Cloud SQL's direct endpoint (the one that bypasses the pooler)
- TLS-secured PostgreSQL:
    - keep `AUTHENTIK_POSTGRESQL__SSLMODE=verify-ca` or use `verify-full` if hostname verification is available

### Deprecated Settings

- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`

    Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.

- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`

    Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.

## Cache settings

##### `AUTHENTIK_CACHE__TIMEOUT`

Timeout for cached data until it expires in seconds.

Defaults to `300`.

##### `AUTHENTIK_CACHE__TIMEOUT_FLOWS`

Timeout for cached flow plans until they expire in seconds.

Defaults to `300`.

##### `AUTHENTIK_CACHE__TIMEOUT_POLICIES`

Timeout for cached policies until they expire in seconds.

Defaults to `300`.

## Worker settings

##### `AUTHENTIK_WORKER__PROCESSES`

Configure how many worker processes should be started for Dramatiq to use. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

Defaults to 1. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

##### `AUTHENTIK_WORKER__THREADS`

Configure how many Dramatiq threads are started per worker. In environments where scaling with multiple replicas of the authentik worker is not possible, this number can be increased to handle higher loads.

Defaults to 2. A value below 2 threads is not recommended, unless you have multiple worker replicas.

##### `AUTHENTIK_WORKER__CONSUMER_LISTEN_TIMEOUT`

Configure how long a worker waits for a PostgreSQL `LISTEN` notification.

Defaults to `seconds=30`.

##### `AUTHENTIK_WORKER__TASK_MAX_RETRIES`

Configure how many times a failing task will be retried before abandoning.

Defaults to 5.

##### `AUTHENTIK_WORKER__TASK_DEFAULT_TIME_LIMIT`

Configure the default duration a task can run for before it is aborted. Some tasks will override this setting based on other settings, such as LDAP source synchronization tasks.

Defaults to `minutes=10`.

##### `AUTHENTIK_WORKER__TASK_PURGE_INTERVAL`

Configure the interval at which old tasks are cleaned up.

Defaults to `days=1`.

##### `AUTHENTIK_WORKER__TASK_EXPIRATION`

Configure how long tasks are kept in the database before they are deleted.

Defaults to `days=30`.

##### `AUTHENTIK_WORKER__SCHEDULER_INTERVAL`

Configure how often the task scheduler runs.

Defaults to `seconds=60`.

## Listen Settings

##### `AUTHENTIK_LISTEN__HTTP`

List of comma-separated `address:port` values for HTTP.

Applies to the Server, the Worker, and Proxy outposts.

Defaults to `[::]:9000`.

##### `AUTHENTIK_LISTEN__HTTPS`

List of comma-separated `address:port` values for HTTPS.

Applies to the Server and Proxy outposts.

Defaults to `[::]:9443`.

##### `AUTHENTIK_LISTEN__LDAP`

List of comma-separated `address:port` values for LDAP.

Applies to LDAP outposts.

Defaults to `[::]:3389`.

##### `AUTHENTIK_LISTEN__LDAPS`

List of comma-separated `address:port` values for LDAPS.

Applies to LDAP outposts.

Defaults to `[::]:6636`.

##### `AUTHENTIK_LISTEN__RADIUS`

List of comma-separated `address:port` values for RADIUS.

Applies to RADIUS outposts.

Defaults to `[::]:1812`.

##### `AUTHENTIK_LISTEN__METRICS`

List of comma-separated `address:port` values for Prometheus metrics.

Applies to all.

Defaults to `[::]:9300`.

##### `AUTHENTIK_LISTEN__DEBUG`

Listening address:port for Go debugging metrics.

Applies to the LDAP, RADIUS, and RAC outposts, which are the remaining Go components.

Defaults to `0.0.0.0:9900`.

##### `AUTHENTIK_LISTEN__DEBUG_PY`

Base listening address:port for the Python debugging server, see [Debugging](../../developer-docs/setup/debugging.mdx).

Applies to the Server and the Worker. The Server listens on this exact port; each Worker process listens on a successive port (`9902`, `9903`, …).

Defaults to `0.0.0.0:9901`.

##### `AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS`

List of comma-separated CIDRs that proxy headers should be accepted from.

Applies to the Server.

Requests directly coming from one an address within a CIDR specified here are able to set proxy headers, such as `X-Forwarded-For`. Requests coming from other addresses will not be able to set these headers.

Defaults to `127.0.0.0/8`, `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fe80::/10`, `::1/128`.

## Storage settings

These settings affect where files are stored. By default, they are stored on disk in the `/data` directory of the authentik container. S3 storage is also supported.

#### `AUTHENTIK_STORAGE__BACKEND`

This parameter defines where to store files. Valid values are `file` and `s3`. For `file` storage, files are stored in a `/data` directory in the container. For `s3`, see below.

Defaults to `file`.

### File storage backend settings

#### `AUTHENTIK_STORAGE__FILE__PATH`

Where to store files on disk.

Defaults to `/data`.

#### `AUTHENTIK_STORAGE__FILE__URL_EXPIRY`

How long generated URLs for file access are valid for.

Defaults to `minutes=15`.

### S3 storage backend settings

For more information on S3 storage, see [S3-compatible storage](../../sys-mgmt/ops/storage-s3/index.mdx).

#### `AUTHENTIK_STORAGE__S3__REGION`

S3 region where the bucket has been created. May be omitted depending on which S3 provider you use.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__ENDPOINT`

Endpoint to use to talk to the S3 storage provider. Overrides the previous region and use_ssl settings.

Must be a valid URL in the form of `https://s3.provider`.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__USE_SSL`

Whether to use HTTPS when talking to the S3 storage providers.

Defaults to `true`.

#### `AUTHENTIK_STORAGE__S3__ADDRESSING_STYLE`

Configure the addressing style used to address a bucket.

Valid values are `auto` and `path`.

Defaults to `auto`.

#### `AUTHENTIK_STORAGE__S3__SIGNATURE_VERSION`

Configure the signing method used for S3 requests.

Defaults to `s3v4`.

Set to `s3` for legacy S3-compatible providers that do not support signature v4.

#### `AUTHENTIK_STORAGE__S3__SESSION_PROFILE`

Profile to use when using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__ACCESS_KEY`

Access key to authenticate to S3. May be omitted if using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__SECRET_KEY`

Secret key to authenticate to S3. May be omitted if using AWS SDK authentication.

Supports hot-reloading.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__SECURITY_TOKEN`

Security token to authenticate to S3. May be omitted.

Supports hot-reloading.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__BUCKET_NAME`

Name of the bucket to use to store files.

#### `AUTHENTIK_STORAGE__S3__CUSTOM_DOMAIN`

Domain to use to create URLs for users. Mainly useful for non-AWS providers.

May include a port. Must include the bucket.

Example: `s3.company:8080/authentik-data`.

Defaults to not set.

#### `AUTHENTIK_STORAGE__S3__SECURE_URLS`

Whether URLs created use HTTPS or HTTP.

Defaults to `true`.

#### `AUTHENTIK_STORAGE__S3__URL_EXPIRY`

How long generated URLs for file access are valid for.

Defaults to `minutes=15`.

### Media storage settings

These settings affect where media files are stored. Those files include applications and sources icons.

#### `AUTHENTIK_STORAGE__MEDIA__BACKEND`

Overrides [`AUTHENTIK_STORAGE__BACKEND`](#authentik_storage__backend)

#### `AUTHENTIK_STORAGE__MEDIA__FILE__[...]`

Overrides [`AUTHENTIK_STORAGE__FILE__[...]`](#file-storage-backend-settings) settings.

#### `AUTHENTIK_STORAGE__MEDIA__S3__[...]`

Overrides [`AUTHENTIK_STORAGE__S3__[...]`](#s3-storage-backend-settings) settings.

These settings affect where media files are stored. Those files include applications and sources icons. By default, they use the same storage settings as the main storage configuration. S3 storage is also supported.

### Reports storage settings

These settings affect where CSV reports are stored.

#### `AUTHENTIK_STORAGE__REPORTS__BACKEND`

Overrides [`AUTHENTIK_STORAGE__BACKEND`](#authentik_storage__backend)

#### `AUTHENTIK_STORAGE__REPORTS__FILE__[...]`

Overrides [`AUTHENTIK_STORAGE__FILE__[...]`](#file-storage-backend-settings) settings.

#### `AUTHENTIK_STORAGE__REPORTS__S3__[...]`

Overrides [`AUTHENTIK_STORAGE__S3__[...]`](#s3-storage-backend-settings) settings.

## authentik settings

### `AUTHENTIK_SECRET_KEY`

Secret key used for cookie signing. Changing this will invalidate active sessions.

:::caution
Prior to 2023.6.0 the secret key was also used for unique user IDs. When running a pre-2023.6.0 version of authentik the key should _not_ be changed after the first install.
:::

### `AUTHENTIK_LOG_LEVEL`

Log level for the server and worker containers. Possible values: `debug`, `info`, `warning`, `error`.

Starting with 2021.12.3, you can also set the log level to `trace`. This has no effect on the core authentik server, but shows additional messages for the embedded outpost.

:::danger
Setting the log level to `trace` will include sensitive details in logs, so it shouldn't be used in most cases.

Logs generated with `trace` should be treated with care as they can give others access to your instance, and can potentially include things like session cookies to authentik **and other pages**.
:::

Defaults to `info`.

### `AUTHENTIK_COOKIE_DOMAIN`

Which domain the session cookie should be set to. By default, the cookie is set to the domain authentik is accessed under.

### `AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__GEOIP`

Path to the GeoIP City database. Defaults to `/geoip/GeoLite2-City.mmdb`. If the file is not found, authentik will skip GeoIP support.

### `AUTHENTIK_EVENTS__CONTEXT_PROCESSORS__ASN`

Path to the GeoIP ASN database. Defaults to `/geoip/GeoLite2-ASN.mmdb`. If the file is not found, authentik will skip GeoIP support.

### `AUTHENTIK_DISABLE_UPDATE_CHECK`

Disable the inbuilt update-checker. Defaults to `false`.

### `AUTHENTIK_ERROR_REPORTING`

- `AUTHENTIK_ERROR_REPORTING__ENABLED`

    Enable error reporting. Defaults to `false`.

    Error reports are sent to https://sentry.io and are used for debugging and general feedback. Anonymous performance data is also sent.

- `AUTHENTIK_ERROR_REPORTING__SENTRY_DSN`

    Sets the DSN for the Sentry API endpoint.

    When error reporting is enabled, the default Sentry DSN will allow the authentik developers to receive error reports and anonymous performance data, which is used for general feedback about authentik, and in some cases, may be used for debugging purposes.

    Users can create their own hosted Sentry account (or self-host Sentry) and opt to collect this data themselves.

- `AUTHENTIK_ERROR_REPORTING__ENVIRONMENT`

    The environment tag associated with all data sent to Sentry. Defaults to `customer`.

    When error reporting has been enabled to aid in debugging issues, this should be set to a unique value, such as an email address.

- `AUTHENTIK_ERROR_REPORTING__SEND_PII`

    Whether or not to send personal data, like usernames. Defaults to `false`.

- `AUTHENTIK_ERROR_REPORTING__EXTRA_ARGS`

    Base64-encoded sentry_init arguments. See [Sentry's documentation](https://docs.sentry.io/platforms/python/configuration/options/) for available options.

### `AUTHENTIK_EMAIL`

The `AUTHENTIK_EMAIL` settings are used to configure SMTP email delivery from authentik.

These global email settings are used for administrator notifications, release and configuration alerts, [notification rules](../../sys-mgmt/events/notifications.mdx), and any [Email stage](../../add-secure-apps/flows-stages/stages/email/) configured to use global settings.

For complete setup examples, testing instructions, and TLS guidance, see the [Email configuration guide](../email.mdx).

- `AUTHENTIK_EMAIL__HOST`

    Default: `localhost`

    SMTP server hostname or IP address.

- `AUTHENTIK_EMAIL__PORT`

    Default: `25`

    SMTP server port. Common values are `25`, `587` for STARTTLS, and `465` for implicit TLS.

- `AUTHENTIK_EMAIL__USERNAME`

    Default: `` (Don't add quotation marks)

    SMTP username. If empty, authentik will not attempt SMTP authentication.

- `AUTHENTIK_EMAIL__PASSWORD`

    Default: `` (Don't add quotation marks)

    SMTP password. If empty, authentik will not attempt SMTP authentication.

- `AUTHENTIK_EMAIL__USE_TLS`

    Default: `false`

    Enable STARTTLS, also called explicit TLS. This is usually used with port `587`.

    Mutually exclusive with `AUTHENTIK_EMAIL__USE_SSL`.

- `AUTHENTIK_EMAIL__USE_SSL`

    Default: `false`

    Enable implicit TLS. This is usually used with port `465`.

    Mutually exclusive with `AUTHENTIK_EMAIL__USE_TLS`.

- `AUTHENTIK_EMAIL__TIMEOUT`

    Default: `10`

    SMTP connection timeout in seconds.

- `AUTHENTIK_EMAIL__FROM`

    Default: `authentik@localhost`

    Email address that authentik will send emails from. This should be a valid address for your domain.

    To include a display name, use the format `Name <account@domain>`.

### `AUTHENTIK_OUTPOSTS`

- `AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE`

    Placeholders:
    - `%(type)s`: Outpost type; proxy, ldap, etc
    - `%(version)s`: Current version; 2021.4.1
    - `%(build_hash)s`: Build hash if you're running a beta version

    Placeholder for outpost docker images. Default: `ghcr.io/goauthentik/%(type)s:%(version)s`.

- `AUTHENTIK_OUTPOSTS__DISCOVER`

    Configure the automatic discovery of integrations. Defaults to `true`.

    By default, the following is discovered:
    - Kubernetes in-cluster config
    - Kubeconfig
    - Existence of a docker socket

### `AUTHENTIK_LDAP__TASK_TIMEOUT_HOURS`

Timeout in hours for LDAP synchronization tasks.

Defaults to `2`.

### `AUTHENTIK_LDAP__PAGE_SIZE`

Page size for LDAP synchronization. Controls the number of objects created in a single task.

Defaults to `50`.

### `AUTHENTIK_LDAP__TLS__CIPHERS`

Allows configuration of TLS Ciphers for LDAP connections used by LDAP sources. Setting applies to all sources.

Defaults to `null`.

### `AUTHENTIK_REPUTATION__EXPIRY`

Configure how long reputation scores should be saved for in seconds.

Defaults to `86400`.

### `AUTHENTIK_SESSION_STORAGE`

:::info Deprecated
This setting is removed as of version 2025.4. Sessions are now exclusively stored in the database. See our [2025.4 release notes](../../releases/2025.4#sessions-are-now-stored-in-the-database) for more information.
:::

If you are running a version earlier than 2025.4, you can configure if the sessions are stored in the cache or the database. Defaults to `cache`. Allowed values are `cache` and `db`. Note that changing this value will invalidate all previous sessions.

### `AUTHENTIK_SESSIONS__UNAUTHENTICATED_AGE`:ak-version[2025.4]

Configure how long unauthenticated sessions last for. Does not impact how long authenticated sessions are valid for. See the [user login stage](../../add-secure-apps/flows-stages/stages/user_login/index.mdx) for session validity.

Defaults to `days=1`.

### `AUTHENTIK_SESSIONS__USER_SWITCHING_AGE`:ak-version[2026.8]

Configure how long the browser cookie that groups sessions for [user account switching](../../users-sources/user/user-switching.mdx) lasts. This setting does not change the validity of the grouped sessions.

Defaults to `days=365`.

### `AUTHENTIK_WEB__WORKERS`

Configure how many gunicorn worker processes should be started (see https://docs.gunicorn.org/en/stable/design.html).

Defaults to 2. A value below 2 workers is not recommended. In environments where scaling with multiple replicas of the authentik server is not possible, this number can be increased to handle higher loads.

### `AUTHENTIK_WEB__THREADS`

Configure how many gunicorn threads a worker processes should have (see https://docs.gunicorn.org/en/stable/design.html).

Defaults to 4.

### `AUTHENTIK_WEB__MAX_REQUESTS`

The maximum number of requests a worker will process before restarting. If this is set to zero then the automatic worker restarts are disabled (see https://gunicorn.org/reference/settings/#max_requests).

Defaults to 1000.

### `AUTHENTIK_WEB__MAX_REQUESTS_JITTER`

The maximum jitter to add to the `AUTHENTIK_WEB__MAX_REQUESTS` setting (see https://gunicorn.org/reference/settings/#max_requests_jitter).

Defaults to 50.

### `AUTHENTIK_WEB__PATH`

Configure the path under which authentik is served. For example to access authentik under `https://my.domain/authentik/`, set this to `/authentik/`. Value _must_ contain both a leading and trailing slash.

Defaults to `/`.

### `AUTHENTIK_WEB__BASE_URL`:ak-version[2026.8]

The base URL under which this authentik instance is reachable, for example `https://authentik.company`.

This option is a bootstrap value. On first start, authentik copies it into the **Base URL** [system setting](../../sys-mgmt/settings.mdx) when that setting has not been configured yet. It never overwrites a Base URL that was already set through the Admin interface or API, and when it is empty authentik falls back to the host configured on the embedded outpost. Once the system setting holds a value, this option is no longer consulted, so it does not need to remain in your environment configuration.

Any trailing slash is removed, so `https://authentik.company` and `https://authentik.company/` are equivalent.

:::info
Set this to the scheme and host only, without a path. All of authentik is served under [`AUTHENTIK_WEB__PATH`](#authentik_web__path) (`/` by default), and that prefix is already part of every link authentik generates. So even when you serve authentik under a subpath, for example `AUTHENTIK_WEB__PATH=/authentik/`, the base URL stays `https://authentik.company`, and generated links resolve under `https://authentik.company/authentik/`.
:::

Defaults to an empty string.

This setting is currently unused until it can be marked as required, starting from authentik version 2026.11.

### `AUTHENTIK_WEB__TIMEOUT_HTTP`

Configure the timeouts for the web HTTP/HTTPS Server. Accepts duration in the format of "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".

- `AUTHENTIK_WEB__TIMEOUT_HTTP_READ_HEADER`

Defaults to `5s`

- `AUTHENTIK_WEB__TIMEOUT_HTTP_READ`

Defaults to `30s`

- `AUTHENTIK_WEB__TIMEOUT_HTTP_WRITE`

Defaults to `60s`

- `AUTHENTIK_WEB__TIMEOUT_HTTP_IDLE`

Defaults to `120s`

## Advanced settings

##### `AUTHENTIK_SKIP_MIGRATIONS`

Whether to skip running migrations on starting authentik. This is destined to advanced setups and not recommended in normal use.

Defaults to `false`.

## System settings

Additional [system settings](../../sys-mgmt/settings.mdx) are configurable using the Admin interface, under **System** > **Settings** or using the API.

## Custom python settings

To modify additional settings further than the options above allow, you can create a custom Python file and mount it to `/data/user_settings.py`. This file will be loaded on startup by both the server and the worker. The [`authentik/root/settings.py` file](https://github.com/goauthentik/authentik/blob/main/authentik/root/settings.py) defines all default settings.

:::caution
Using these custom settings is not supported and can prevent your authentik instance from starting. Use with caution.
:::