How to Change Logto Configuration: Environment Variables and Tenant Settings

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.

Key environment variables include:

• DATABASE_URL (or DB_URL) – The PostgreSQL connection string, read in packages/cli/src/index.ts via process.env[ConfigKey.DatabaseUrl]
• ENDPOINT – Base URL for user-facing APIs, consumed in 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
• IS_CLOUD – Indicates cloud-hosted deployments, referenced in packages/console/vite.config.ts

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

# .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:

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, 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 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. This utility reads and writes values directly to the database.

Rotate OIDC cookie keys:

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

Rotate OIDC private keys:

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:

// 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 – Defines the LogtoConfigKey union and associated TypeScript types
• 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 – OpenAPI specification for the Management API endpoints
• 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.

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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}