Configuration

All configuration is done via environment variables.

Core

Variable	Required	Default	Description
BASE_URL	✅	—	Public URL of the AUMS instance (e.g. https://admin.example.com)
BETTER_AUTH_SECRET	✅	—	32-byte random secret for session signing. Generate with npm run auth:secret
PROVIDER_CONFIG_ENCRYPTION_KEY	—	BETTER_AUTH_SECRET	Key that encrypts secret provider settings at rest. Changing it (or the fallback) makes stored secrets unreadable: re-enter them in the settings

Caution

PLAN_TIER must match the Docker image you are using. The plan is baked into the image at build time.

Database

Variable	Required	Default	Description
DATABASE_URL	✅	—	PostgreSQL connection string (e.g. postgresql://user:pass@host:5432/aums)
DATABASE_DIALECT	—	postgresql	Database dialect. Only postgresql is supported
DATABASE_CLIENT	—	postgresql	Database client. Only postgresql is supported
DATABASE_AUTO_MIGRATE	—	true	Run migrations automatically on startup

Admin audit trail

Variable	Required	Default	Description
WEBHOOK_ALLOW_PRIVATE_ADDRESSES	—	false	Allow webhooks to http URLs and to private network addresses. Only for self-hosted instances with trusted admins
REQUIRE_DELETE_APPROVAL	—	false	Business tier: user deletions need a second admin’s approval
ADMIN_AUDIT_RETENTION_DAYS	—	—	Delete admin actions older than this many days, daily at 03:17 UTC. Unset keeps them forever. Run once by hand with npm run audit:prune

Email

Variable	Required	Default	Description
EMAIL_FROM	✅	—	Sender address (e.g. AUMS <noreply@example.com>)
EMAIL_SERVER	✅	—	SMTP connection string (e.g. smtps://user:pass@smtp.example.com)

OIDC / SSO (optional)

Protect the AUMS dashboard behind your own OpenID Connect provider.

Variable	Required	Default	Description
AUTH_CLIENT_OPENID_CONFIGURATION_URL	—	—	OIDC discovery URL (e.g. https://oauth.example.com)
AUTH_CLIENT_ID	—	—	OIDC client ID
AUTH_CLIENT_SECRET	—	—	OIDC client secret
AUTH_CLIENT_SCOPE	—	openid profile email	Space-separated OIDC scopes

Auth0

Variable	Required	Description
AUTH0_DOMAIN	✅	Auth0 tenant domain (e.g. your-tenant.auth0.com)
AUTH0_CLIENT_ID	✅	Management API M2M application client ID
AUTH0_CLIENT_SECRET	✅	Management API M2M application client secret
AUTH0_DEFAULT_CONNECTION	—	Database connection used to create users, and to scope users when an organization has no connection configured

Firebase

Variable	Required	Description
FIREBASE_PROJECT_ID	✅	GCP / Firebase project ID
FIREBASE_PRIVATE_KEY	✅	Service account private key (PEM, include newlines as \n)
FIREBASE_CLIENT_EMAIL	✅	Service account email address

AWS Cognito

Variable	Required	Description
COGNITO_REGION	✅	AWS region (e.g. us-east-1)
COGNITO_USER_POOL_ID	✅	User pool ID (e.g. us-east-1_xxxxxxxxx)
AWS_ACCESS_KEY_ID	✅	AWS access key ID
AWS_SECRET_ACCESS_KEY	✅	AWS secret access key

SCIM

Variable	Required	Default	Description
SCIM_BASE_URL	✅	—	Base URL of the SCIM 2.0 service provider (e.g. https://idp.example.com/scim/v2)
SCIM_BEARER_TOKEN	✅	—	Bearer token authorized against the SCIM service provider
SCIM_GROUPS_ENABLED	—	true	Set to false if the service provider does not expose /Groups

See the SCIM provider guide for details, including how to spin up cerberauth/scimply as a local test server.