Configuration Reference

This is the complete configuration reference for all Sovereign services. Configuration is provided via environment variables (recommended for containerized deployments) or appsettings.json files.

Environment Variable Syntax

.NET configuration uses __ (double underscore) as a section separator in environment variables. For example, Auth:Mode in a JSON config file becomes Auth__Mode as an environment variable.

Engine API

The Engine API is the core Workflows service — it orchestrates execution, manages state, and exposes the REST API.

Database

Variable	Required	Default	Description
`ConnectionStrings__Postgres`	Yes	—	PostgreSQL connection string for the workflows database

Authentication

Variable	Required	Default	Description
`Authentication__Authority`	Yes	—	Auth Service URL for JWT validation
`Authentication__Issuer`	No	`dataworkflows-engine`	Expected JWT issuer claim
`Authentication__Audience`	No	`dataworkflows-api`	Expected JWT audience claim
`Auth__Mode`	No	`Bypass`	Authentication mode: `Bypass`, `Local`, or `Oidc`

Auth Service Connection

Variable	Required	Default	Description
`AuthService__BaseUrl`	Yes	—	URL of the Auth Service
`AuthService__TenantServiceKey`	Yes	—	Service key for authenticating to the Auth Service
`AuthService__TimeoutSeconds`	No	`30`	HTTP request timeout for Auth Service calls

Orchestration

These settings control how workflows execute.

Variable	Required	Default	Description
`Orchestration__MaxParallelActions`	No	`10`	Maximum concurrent steps per execution
`Orchestration__DefaultActionTimeout`	No	`00:05:00`	Default timeout for a single step (5 minutes)
`Orchestration__DefaultWorkflowTimeout`	No	`01:00:00`	Default timeout for an entire workflow (1 hour)
`Orchestration__MaxWorkflowNestingDepth`	No	`5`	Maximum subworkflow nesting depth
`Orchestration__AllowSubworkflowRecursion`	No	`false`	Whether a workflow can call itself as a subworkflow
`Orchestration__AllowAsyncSubworkflows`	No	`true`	Whether subworkflows can run asynchronously

Retry Policy

Controls automatic retry behavior when steps fail with transient errors.

Variable	Required	Default	Description
`Orchestration__RetryPolicy__MaxAttempts`	No	`3`	Maximum retry attempts per step
`Orchestration__RetryPolicy__InitialDelay`	No	`00:00:02`	Wait time before the first retry (2 seconds)
`Orchestration__RetryPolicy__BackoffFactor`	No	`2.0`	Multiplier for each subsequent retry delay
`Orchestration__RetryPolicy__UseJitter`	No	`true`	Add randomness to retry timing to avoid thundering herd

Message Queue

Variable	Required	Default	Description
`RabbitMQ__Host`	Yes	—	RabbitMQ hostname
`RabbitMQ__Port`	No	`5672`	RabbitMQ AMQP port
`RabbitMQ__Username`	Yes	—	RabbitMQ username
`RabbitMQ__Password`	Yes	—	RabbitMQ password
`RabbitMQ__VirtualHost`	No	`/`	RabbitMQ virtual host

License

Variable	Required	Default	Description
`License__FilePath`	Yes	—	Path to your `.lic` license file
`License__Issuer`	Yes	—	Expected license issuer (provided with your license)

License Heartbeat

Connected deployments (all tiers except Air-Gapped) periodically verify their license with the Portal.

Variable	Required	Default	Description
`LicenseHeartbeat__HeartbeatUrl`	No	`https://portal.nemorion.com`	Portal URL for license verification
`LicenseHeartbeat__LicenseKey`	No	—	Your license key for heartbeat authentication

Webhooks

Variable	Required	Default	Description
`Webhooks__Mode`	No	`embedded`	Webhook receiver mode: `embedded` (runs inside Engine) or `gateway` (separate service)
`Webhooks__AwaitTimeoutSeconds`	No	`30`	Timeout for synchronous webhook responses
`Webhooks__MaxAwaitTimeoutSeconds`	No	`120`	Maximum allowed timeout for await-completion webhooks

Swagger / API Documentation

Variable	Required	Default	Description
`Swagger__Enabled`	No	`true`	Set to `false` to disable Swagger UI in production

Service Key

Variable	Required	Default	Description
`ServiceKeyAuthentication__GlobalServiceKey`	No	—	Service key accepted from internal services calling the Engine API

Audit

Variable	Required	Default	Description
`Audit__ServiceName`	No	`engine-api`	Service name in audit log entries
`Audit__Enabled`	No	`true`	Enable audit logging (requires audit capability in your license)
`Audit__ConnectionString`	No	—	Separate database for audit logs (optional)
`Audit__RetentionDays`	No	`90`	How long to keep audit records

Template Engine

Variable	Required	Default	Description
`TemplateEngine__MaxIterations`	No	`1000`	Maximum template rendering iterations (prevents infinite loops)
`TemplateEngine__CacheSize`	No	`100`	Number of compiled templates to cache

Auth Service

The Auth Service handles authentication, token issuance, credential storage, and OAuth flows for all products.

Database

Variable	Required	Default	Description
`ConnectionStrings__AuthDb`	Yes	—	Auth database connection string
`ConnectionStrings__Redis`	No	—	Redis connection string for caching and distributed locking

Authentication Mode

Variable	Required	Default	Description
`Auth__Mode`	No	`Bypass`	`Bypass`, `Local`, or `Oidc`

See Authentication Setup for detailed configuration of each mode.

JWT Bearer Validation

These keys configure how the Auth Service validates incoming bearer tokens on its protected endpoints (e.g., /api/users/me, /api/preferences, SCIM provisioning). They are also consumed by every other Sovereign service that accepts Auth-issued tokens — so each service can fetch the Auth Service's JWKS to validate signatures.

Variable	Required	Default	Description
`Authentication__Authority`	Yes (OIDC)	—	This Auth Service's externally-reachable URL. JWT bearer middleware appends `/.well-known/openid-configuration` to fetch JWKS for incoming token validation. Must match the URL every consuming service uses.
`Authentication__Audience`	No	`auth-service`	Expected JWT audience claim
`Authentication__Issuer`	No	—	Expected JWT issuer claim (defaults to the Authority value)

OIDC mode requires both Authority keys

In OIDC mode, the Auth Service wears two hats: it is the OIDC client (redirects users to your IdP for login) and the JWT issuer (signs and validates tokens for the rest of the platform). Each role has its own configuration:

Auth__Oidc__Authority — your IdP's discovery URL (e.g., https://keycloak.example.com/realms/your-realm). Drives the login redirect.
Authentication__Authority — this Auth Service's own URL (e.g., https://auth.your-company.com). Drives JWT signature validation here and on every consumer.

Both keys must be set in OIDC mode. The Auth Service fails fast at startup with a pointer back to this section if Authentication__Authority is missing.

Local Mode

Variable	Required	Default	Description
`Auth__Local__AdminUser__Email`	No	`admin@local`	Admin login email
`Auth__Local__AdminUser__Password`	Yes (Local)	—	Admin password (minimum 12 characters)
`Auth__Local__AdminUser__TenantId`	No	`default`	Tenant ID for the admin
`Auth__Local__AdminUser__Roles__0`	No	`admin`	Roles assigned to the admin

OIDC Mode

These keys configure the OIDC client (the part of the Auth Service that talks to your IdP for login). For the keys that configure JWT validation here and on every downstream service, see JWT Bearer Validation above — both sets are required in OIDC mode.

Variable	Required	Default	Description
`Auth__Oidc__Authority`	Yes (OIDC)	—	Identity provider discovery URL (your IdP, e.g., Keycloak realm)
`Auth__Oidc__ClientId`	Yes (OIDC)	—	OAuth client ID registered with your IdP
`Auth__Oidc__ClientSecret`	Yes (OIDC)	—	OAuth client secret
`Auth__Oidc__ApplicationBaseUrl`	Yes (OIDC)	—	Your deployment's public URL
`Auth__Oidc__CallbackPath`	No	`/auth/callback`	OAuth redirect path
`Auth__Oidc__Scopes`	No	`openid, profile, email`	Scopes to request from the IdP

Token Configuration

Variable	Required	Default	Description
`Auth__PlatformToken__Issuer`	No	`dataworkflows-engine`	JWT issuer claim
`Auth__PlatformToken__Audience`	No	`dataworkflows-api`	JWT audience claim
`Auth__PlatformToken__AccessTokenExpirationMinutes`	No	`15`	Access token lifetime
`Auth__PlatformToken__RefreshTokenExpirationDays`	No	`7`	Refresh token lifetime
`Auth__PlatformToken__SigningKey__Source`	No	`File`	`File` or `Environment`
`Auth__PlatformToken__SigningKey__Path`	No	`./keys/signing.key`	Path to signing key file
`Auth__PlatformToken__SigningKey__GenerateIfMissing`	No	`false`	Auto-generate if missing (dev only)

Credential Encryption

Variable	Required	Default	Description
`Encryption__MasterKeyId`	Yes	—	Active encryption key identifier
`Encryption__MasterKey`	Yes	—	Encryption master key value
`Encryption__Algorithm`	No	`AES-256-GCM`	Encryption algorithm
`Encryption__KeyProvider__Type`	No	`Environment`	Key provider: `Environment`, `AzureKeyVault`, or `HashiCorpVault`

OAuth Settings

Variable	Required	Default	Description
`OAuth__CallbackUrl`	No	—	Callback URL for connector OAuth flows
`OAuth__StateExpirationMinutes`	No	`10`	OAuth state parameter time-to-live
`OAuth__RequirePkce`	No	`true`	Require PKCE for all OAuth flows

Caching

Variable	Required	Default	Description
`Caching__Provider`	No	`Redis`	`Redis` or `InMemory`
`Caching__EncryptedTokenCacheTtlMinutes`	No	`60`	Encrypted token cache lifetime

Audit

Variable	Required	Default	Description
`Audit__LogToDatabase`	No	`true`	Write audit events to the database
`Audit__LogToSerilog`	No	`true`	Write audit events to structured logs
`Audit__RetentionDays`	No	`90`	Audit log retention period in days

Rate Limiting

Variable	Required	Default	Description
`RateLimiting__Strict__PermitLimit`	No	`10`	Max requests per window for credential endpoints
`RateLimiting__Strict__WindowSeconds`	No	`60`	Window duration for strict rate limit
`RateLimiting__Relaxed__PermitLimit`	No	`60`	Max requests per window for metadata endpoints
`RateLimiting__Relaxed__WindowSeconds`	No	`60`	Window duration for relaxed rate limit

Executor Worker

The Executor Worker processes workflow steps by calling connector services and reporting results.

Database

Variable	Required	Default	Description
`ConnectionStrings__DefaultConnection`	Yes	—	PostgreSQL connection string

Auth Service

Variable	Required	Default	Description
`AuthService__BaseUrl`	Yes	—	Auth Service URL for credential resolution
`AuthService__TenantServiceKey`	Yes	—	Service key for Auth Service access

Message Queue

Same settings as the Engine API (RabbitMQ__Host, RabbitMQ__Port, RabbitMQ__Username, RabbitMQ__Password, RabbitMQ__VirtualHost).

Connector URLs

Tell the Executor Worker where to find each connector service:

Variable	Required	Default	Description
`ConnectorUrls__sample`	No	—	Connector Host URL
`ConnectorUrls__llm`	No	—	LLM Connector URL
`ConnectorUrls__connectorgen`	No	—	ConnectorGen Connector URL

Service Key

Variable	Required	Default	Description
`ServiceKeyAuthentication__GlobalServiceKey`	No	—	Key for authenticating to connector services

License

Same settings as Engine API (License__FilePath, License__Issuer).

MCP Server

The MCP Server provides AI agent access to your workflows.

Database

Variable	Required	Default	Description
`ConnectionStrings__Postgres`	Yes	—	PostgreSQL connection string

Authentication

Same settings as Engine API (Authentication__Authority, Authentication__Issuer, Authentication__Audience).

Engine API Connection

Variable	Required	Default	Description
`EngineApi__BaseUrl`	Yes	—	Engine API URL for executing platform tools
`EngineApi__ServiceKey`	Yes	—	Service key for Engine API access

LLM Configuration

Variable	Required	Default	Description
`Llm__ConfigFilePath`	No	—	Path to the LLM provider configuration file

Public URLs (OAuth Discovery)

Variable	Required	Default	Description
`AuthService__PublicBaseUrl`	No	—	Public URL of the Auth Service (for OAuth metadata)
`Mcp__PublicBaseUrl`	No	—	Public URL of the MCP Server (for resource metadata)

License

Same settings as Engine API (License__FilePath, License__Issuer).

Orbit API

The Orbit API provides the backend for the Orbit collaboration platform.

Database

Variable	Required	Default	Description
`ConnectionStrings__DefaultConnection`	Yes	—	PostgreSQL connection string for the Orbit database

Authentication

Variable	Required	Default	Description
`Authentication__Authority`	Yes	—	Auth Service URL for JWT validation
`Authentication__Issuer`	No	`dataworkflows-engine`	Expected JWT issuer
`Authentication__Audience`	No	`dataworkflows-api`	Expected JWT audience

Infrastructure

PostgreSQL

Variable	Required	Default	Description
`POSTGRES_DB`	No	`dataworkflows`	Primary database name
`POSTGRES_USER`	No	`postgres`	Database username
`POSTGRES_PASSWORD`	Yes	—	Database password
`AUTH_POSTGRES_DB`	No	`auth`	Auth database name
`AUTH_POSTGRES_USER`	No	`auth_user`	Auth database username
`AUTH_POSTGRES_PASSWORD`	Yes	—	Auth database password

RabbitMQ

Variable	Required	Default	Description
`RABBITMQ_USER`	No	`workflow`	RabbitMQ username
`RABBITMQ_PASSWORD`	Yes	—	RabbitMQ password

LLM Provider API Keys

Variable	Required	Description
`OPENAI_API_KEY`	No	OpenAI API key for GPT models
`ANTHROPIC_API_KEY`	No	Anthropic API key for Claude models
`AZURE_OPENAI_API_KEY`	No	Azure OpenAI API key
`GEMINI_API_KEY`	No	Google Gemini API key

At least one provider key is required for AI-powered workflow features.

Service-to-Service Keys

Variable	Description
`AUTH_TENANT_SERVICE_KEY`	Key for services calling the Auth Service
`ENGINE_GLOBAL_SERVICE_KEY`	Key for services calling the Engine API
`CONNECTOR_GLOBAL_SERVICE_KEY`	Key for the Executor Worker calling connector services

Generate unique random values for each:

openssl rand -base64 32

Default Ports

Service	Port	Description
Reverse Proxy	4723	Public entry point (UI + API)
Engine API	5003	Workflow engine
LLM Connector	5015	AI provider gateway
MCP Server	5016	AI agent access
Auth Service	5017	Authentication
Connector Host	5018	Connector plugins
ConnectorGen Connector	5020	Connector generation
PostgreSQL	5433	Primary database
RabbitMQ (AMQP)	5672	Message broker
RabbitMQ (Management)	15672	Broker management UI
Redis	6379	Cache
PgAdmin	5050	Database management UI

Secrets Management

Never commit secrets to version control. Use environment variables, Docker secrets, or a secrets manager (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) for all passwords, API keys, and encryption keys.

Next Steps

Deployment Guide — deploy with Docker Compose using these settings
Authentication Setup — detailed auth mode configuration
Security Overview — security considerations for production configuration