# How to Change Logto Configuration: Environment Variables and Tenant Settings

> Learn how to change Logto configuration using environment variables for static settings or PostgreSQL tenant updates via CLI/API for dynamic runtime adjustments. Master Logto configuration today.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-07-03

---

**You can change Logto configuration by modifying environment variables for static deployment settings or by updating the tenant configuration stored in the PostgreSQL database via the CLI or Management API for dynamic runtime behavior.**

The Logto open-source identity platform (`logto-io/logto`) uses a dual-layer configuration system that separates infrastructure-level settings from mutable tenant-specific options. According to the source code in the Logto monorepo, configuration is handled either through Node.js `process.env` at startup or through the `logto_configs` database table during runtime.

## Layer 1: Environment Variable Configuration

Environment variables control static deployment parameters and are read directly from `process.env` across the CLI, Core, and Console packages. These values are injected into the frontend via Vite’s `import.meta.env` in packages like [`packages/experience/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/vite.config.ts).

Key environment variables include:

- **`DATABASE_URL`** (or `DB_URL`) – The PostgreSQL connection string, read in [`packages/cli/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/index.ts) via `process.env[ConfigKey.DatabaseUrl]`
- **`ENDPOINT`** – Base URL for user-facing APIs, consumed in [`packages/experience/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/vite.config.ts)
- **`ADMIN_ENDPOINT`** – Base URL for administrative APIs
- **`DEV_FEATURES_ENABLED`** – Toggles development-only features, checked in [`packages/experience/src/constants/env.ts`](https://github.com/logto-io/logto/blob/main/packages/experience/src/constants/env.ts)
- **`IS_CLOUD`** – Indicates cloud-hosted deployments, referenced in [`packages/console/vite.config.ts`](https://github.com/logto-io/logto/blob/main/packages/console/vite.config.ts)

Create a `.env` file in the repository root for local development:

```bash

# .env

DATABASE_URL=postgres://postgres:p0stgr3s@localhost:5432/logto
ENDPOINT=http://localhost:3001
ADMIN_ENDPOINT=http://localhost:3002
DEV_FEATURES_ENABLED=true

```

For Docker deployments, pass variables via the `-e` flag:

```bash
docker run -d \
  -e DATABASE_URL=postgres://postgres:p0stgr3s@db:5432/logto \
  -e ENDPOINT=http://localhost:3001 \
  -e ADMIN_ENDPOINT=http://localhost:3002 \
  logto/logto:latest

```

## Layer 2: Tenant Configuration (Database)

Mutable configuration is stored in the `logto_configs` table and persisted across deployments. The schema for these keys is defined in [`packages/schemas/src/types/logto-config/index.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/types/logto-config/index.ts), which exports the `LogtoOidcConfigKey` and `LogtoTenantConfigKey` enums.

Common tenant configuration keys include:

- **`oidc.privateKeys`** – JSON array of PEM-encoded signing keys for token rotation
- **`oidc.cookieKeys`** – Array of signing keys for session cookies
- **`adminConsole`** – UI customization settings (logo, theme colors)
- **`cloudConnection`** – Cloud-specific feature flags

Default values are seeded from [`packages/schemas/src/seeds/logto-config.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/seeds/logto-config.ts) when creating a new tenant.

### Updating Configuration via CLI

The Logto CLI provides a `config` command implemented in [`packages/cli/src/commands/database/config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/config.ts). This utility reads and writes values directly to the database.

Rotate OIDC cookie keys:

```bash
pnpm cli config set oidc.cookieKeys "$(pnpm cli config generate-key)"

```

Rotate OIDC private keys:

```bash
pnpm cli config rotate oidc.privateKeys

```

### Updating Configuration via Management API

For programmatic changes, send a PATCH request to the tenant-config endpoint defined in [`packages/core/src/routes/tenant-config.openapi.json`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/tenant-config.openapi.json):

```typescript
// Node.js example using fetch
await fetch('http://localhost:3002/api/tenant-config', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.MANAGEMENT_API_TOKEN}`,
  },
  body: JSON.stringify({
    key: 'adminConsole',
    value: {
      logo: 'https://cdn.example.com/logo.png',
      primaryColor: '#4A90E2'
    },
  }),
});

```

## Key Configuration Files

Understanding where Logto reads configuration helps when troubleshooting or extending the platform:

- **[`packages/schemas/src/types/logto-config/index.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/types/logto-config/index.ts)** – Defines the `LogtoConfigKey` union and associated TypeScript types
- **[`packages/cli/src/commands/database/config.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/commands/database/config.ts)** – Implements the `config set`, `config get`, and `config rotate` CLI operations
- **[`packages/core/src/routes/tenant-config.openapi.json`](https://github.com/logto-io/logto/blob/main/packages/core/src/routes/tenant-config.openapi.json)** – OpenAPI specification for the Management API endpoints
- **[`packages/schemas/src/seeds/logto-config.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/seeds/logto-config.ts)** – Default configuration values for new tenants

## Summary

- **Environment variables** handle static infrastructure settings like database URLs and endpoints, requiring a service restart to take effect.
- **Tenant configuration** stored in the `logto_configs` table manages dynamic runtime behavior including OIDC keys and admin console branding.
- Use the CLI command `pnpm cli config set <key> <value>` for manual database updates from the terminal.
- Use the Management API `PATCH /api/tenant-config` for programmatic configuration changes in production environments.
- All configuration keys are type-safe and defined in [`packages/schemas/src/types/logto-config/index.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/types/logto-config/index.ts).

## Frequently Asked Questions

### What is the difference between environment variables and tenant configuration in Logto?

Environment variables are read at startup from `process.env` and control infrastructure-level settings like the PostgreSQL connection string and base URLs. Tenant configuration is stored in the `logto_configs` database table and persists across restarts, managing runtime behavior such as OIDC signing keys and admin console theming.

### How do I rotate OIDC keys in Logto?

Use the CLI command `pnpm cli config rotate oidc.privateKeys` to rotate private signing keys, or `pnpm cli config set oidc.cookieKeys "$(pnpm cli config generate-key)"` to update cookie encryption keys. These commands update the values stored in the `logto_configs` table without requiring service downtime.

### Where are the configuration key definitions located?

All configuration keys are centrally defined in [`packages/schemas/src/types/logto-config/index.ts`](https://github.com/logto-io/logto/blob/main/packages/schemas/src/types/logto-config/index.ts), which exports the `LogtoOidcConfigKey` and `LogtoTenantConfigKey` enums. This file serves as the source of truth for valid configuration keys throughout the codebase.

### Can I change configuration without restarting Logto?

Yes, but only for tenant configuration stored in the database. Changes made via the CLI (`pnpm cli config`) or Management API (`PATCH /api/tenant-config`) take effect immediately. Environment variable changes require a service restart because they are read once during the Node.js boot process in files like [`packages/cli/src/index.ts`](https://github.com/logto-io/logto/blob/main/packages/cli/src/index.ts).