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

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_ROUTE_PREFIX	Path prefix the SDK routes are mounted under. Scopes the refresh-cookie.	no	/v1/auth
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

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

Logging

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

See also

• Production checklist — pre-launch audit.
• Configuration reference — programmatic config field-by-field.