Environment variables

Every environment variable the SDK reads, what it does, and whether it is required.

The SDK itself reads no environment variables directly. Hosts construct identsphere_core::AuthServiceConfig, identsphere_axum::AppConfig, and the database URL programmatically. The variable names below are conventions — they're what the example app reads, what the CLI reads, and what these docs assume. Hosts that prefer different names can use them; the SDK doesn't care.

Keeping to these names means a customer can copy the example .env into their own deployment with a one-line dotenvy::dotenv() call and have things work.

Database

Variable	Purpose	Required	Default	Read by
`DATABASE_URL`	Postgres connection URL. `postgres://user:pw@host:port/db`.	yes	—	`identsphere_axum::connect_postgres`, CLI
`IDENTSPHERE_SCHEMA`	Postgres schema name. Must be a plain ASCII identifier.	no	`IdentSphere`	`identsphere_axum::connect_postgres`, CLI
`IDENTSPHERE_AUTO_MIGRATE`	When truthy (`1\|true\|TRUE\|yes`), `identsphere-server` applies the SQL migrations on boot — after connecting to Postgres and before serving — instead of requiring a manual `identsphere-cli migrate up`. Idempotent; fails closed if a migration errors.	no	off	`identsphere-server`
`IDENTSPHERE_MIGRATIONS_DIR`	Directory the `*.sql` migration files are read from when `IDENTSPHERE_AUTO_MIGRATE` is on. The Docker image copies `migrations/` to `/migrations`; point it at `./migrations` for local runs.	no	`/migrations`	`identsphere-server`

The schema name is interpolated into SET search_path TO <schema>, public on every connection acquired from the pool. Schema isolation is the supported multi-tenant model — production deployments should not share public with other applications.

JWT issuance

Variable	Purpose	Required	Default
`IDENTSPHERE_JWT_SECRET`	HS256 signing key. Minimum 32 bytes (HMAC-SHA256 needs ≥256 bits of entropy).	yes	—
`IDENTSPHERE_ISSUER`	`iss` claim on every minted JWT.	no	`IdentSphere`
`IDENTSPHERE_ACCESS_EXPIRY_SECS`	Access-token TTL, seconds.	no	`900` (15 min)
`IDENTSPHERE_REFRESH_EXPIRY_SECS`	Refresh-token TTL, seconds.	no	`2592000` (30 days)

::: warning Rotating IDENTSPHERE_JWT_SECRET invalidates every outstanding session. There is no grace-period second-key window yet. Plan for forced sign-out. :::

Application identity

Variable	Purpose	Required	Default
`IDENTSPHERE_APP_NAME`	User-facing product name. Used in email subjects.	no	`IdentSphere`
`IDENTSPHERE_PUBLIC_BASE_URL`	Canonical public URL of the host.	yes (prod)	`http://localhost:3000`
`IDENTSPHERE_FROM_EMAIL`	Sender address for transactional emails.	yes (prod)	`no-reply@example.com`
`IDENTSPHERE_COOKIES_SECURE`	Toggle the `Secure` cookie attribute. Must be `true` in production.	no	`false`
`IDENTSPHERE_COOKIE_SAMESITE`	`SameSite` for session cookies: `Lax` (default; same-origin first-party web), `None` (a cross-origin SPA — lets the httpOnly refresh cookie ride a cross-origin credentialed fetch, so a different-origin SPA gets httpOnly refresh with no BFF and no localStorage; CSRF stays covered by the double-submit token, and `Secure` is forced), or `Strict`.	no	`Lax`
`IDENTSPHERE_ROUTE_PREFIX`	Path prefix the SDK routes are mounted under. Scopes the refresh-cookie.	no	`/v1/auth`
`IDENTSPHERE_WEBHOOK_ENDPOINTS`	Enable outbound auth-event webhooks. Comma-separated `url\|secret` pairs; each mapped audit event is HMAC-SHA256-signed and POSTed to every endpoint. Empty = disabled.	no	(unset)
`IDENTSPHERE_INITIAL_OWNER_EMAIL`	Bootstrap the first platform admin: promotes this (existing, email-verified) user to `account_owner` while no owner exists. Hijack-safe + idempotent. See Admin console.	no	(unset)
`IDENTSPHERE_SERVE_ADMIN`	Serve the bundled admin console at `/admin`. Set `false` for a headless / API-only deployment.	no	`true`
`IDENTSPHERE_CONFIG_KEY`	32-byte (base64 or hex) master key that encrypts dashboard-managed provider secrets at rest. Unset = dashboard secret storage disabled (env-var fallback). See Secrets & encryption.	no	(unset)
`IDENTSPHERE_CONFIG_KEY_PREVIOUS`	Comma-separated decrypt-only keys for zero-downtime rotation of `IDENTSPHERE_CONFIG_KEY`.	no	(unset)
`IDENTSPHERE_STEP_UP_TTL_SECS`	Step-up MFA assertion lifetime.	no	`1800` (30 min)
`IDENTSPHERE_TEST_MODE`	Sandbox mode: outbound email is suppressed, responses are tagged. See Test mode.	no	`false`

WebAuthn / passkeys

Variable	Purpose	Required	Default
`IDENTSPHERE_RP_ID`	WebAuthn Relying Party ID. Host of `public_base_url`, no scheme/port.	yes (passkeys)	`localhost`
`IDENTSPHERE_RP_ORIGIN`	WebAuthn origin: full URL with scheme.	yes (passkeys)	`http://localhost:3000`
`IDENTSPHERE_RP_NAME`	User-facing RP name.	no	`IdentSphere`

WebAuthn requires HTTPS in browsers; http://localhost is the only exception.

OAuth providers

Optional. Missing client IDs mean the provider's /start endpoint returns 404.

Variable	Purpose
`IDENTSPHERE_OAUTH_GOOGLE_CLIENT_ID`	Google OAuth 2.0 client ID
`IDENTSPHERE_OAUTH_GOOGLE_CLIENT_SECRET`	Google OAuth 2.0 client secret
`IDENTSPHERE_OAUTH_GITHUB_CLIENT_ID`	GitHub OAuth App client ID
`IDENTSPHERE_OAUTH_GITHUB_CLIENT_SECRET`	GitHub OAuth App client secret
`IDENTSPHERE_OAUTH_RP_REDIRECTS`	Comma-separated allowlist of exact absolute relying-party callback URLs permitted to drive the cross-origin OAuth Authorization-Code + PKCE flow. Empty by default = legacy behavior (host-relative `redirect_to` + first-party cookies only; absolute redirects refused — no open redirect). An allowlisted absolute `redirect_to` requires a PKCE `S256` challenge at `/start`; pair it with the RP origin in `CORS_ALLOW_ORIGINS`. See Cross-origin OAuth.

Provider callback URL: {public_base_url}/v1/auth/oauth/{provider}/callback.

Email transport

The SDK ships LogOnlySender for dev (prints to stdout). Production hosts swap in their own identsphere_core::providers::EmailSender implementation. The variables below are conventions; the SDK doesn't read them.

Variable	Purpose	Default
`IDENTSPHERE_SMTP_HOST`	SMTP relay hostname	—
`IDENTSPHERE_SMTP_PORT`	SMTP port	`587`
`IDENTSPHERE_SMTP_USER`	SMTP username	—
`IDENTSPHERE_SMTP_PASSWORD`	SMTP password	—

Frontend (`@identsphere/react`)

The React SDK has no import.meta.env reads of its own. The host injects the API base URL via the provider's config prop:

<AuthProvider config={{ apiBaseUrl: import.meta.env.VITE_AUTH_API_URL }}>

By convention:

Variable	Purpose	Required
`VITE_AUTH_API_URL`	Origin where the auth backend is mounted.	yes

Licensing

IdentSphere verifies its license key locally (offline) against an embedded public key — no network calls. With neither variable set, the server runs in the free Community tier (full core authentication). Premium features (SAML, SCIM, audit-log export) require a license key. See License keys.

Variable	Purpose	Required	Default	Read by
`IDENTSPHERE_LICENSE_FILE`	Filesystem path to a file containing the license JWT. Checked first.	no	—	`identsphere-server`
`IDENTSPHERE_LICENSE`	The license JWT itself, inline. Used if `IDENTSPHERE_LICENSE_FILE` is unset.	no	—	`identsphere-server`

Logging

Variable	Purpose
`RUST_LOG`	`tracing_subscriber` filter. `info,identsphere=debug` is a good starting point.

Database​

JWT issuance​

Application identity​

WebAuthn / passkeys​

OAuth providers​

Email transport​

Frontend (@identsphere/react)​

Licensing​

Logging​

See also​