Configuration Details

Ed-Fi API v8 is configurable through appsettings.json in each service. This page documents the most common settings. Environment variables override appsettings.json values using the double-underscore __ separator for hierarchy — for example, AppSettings__Datastore=mssql. No special prefix is required.

Ed-Fi API Settings

Required Settings

The Ed-Fi API requires a database connection, a reachable Configuration Service, and JWT authentication settings to start. In the Docker Compose setup these are provided via the .env file; in other deployments configure them directly in appsettings.json or via environment variables. The JwtAuthentication section points the Ed-Fi API at the token authority — see Identity Provider for the required keys.

• AppSettings:Datastore

  Example	postgresql
  Description	Primary database engine for the DMS. Valid values: postgresql, mssql

• ConfigurationServiceSettings:BaseUrl

  Example	http://ed-fi-api-config:8081
  Description	Base URL of the Configuration Service. The Ed-Fi API contacts this URL at runtime to retrieve claim sets, data stores, and application context

• ConfigurationServiceSettings:EncryptionKey

  Example	MySecretKey1234567890123456789012
  Description	Key used to decrypt data store connection strings stored in the Configuration Service. Must match DatabaseSettings:EncryptionKey in the Configuration Service. Recommended: a 32-character ASCII string. Set via DMS_CONFIG_DATABASE_ENCRYPTION_KEY environment variable

• AppSettings:AuthenticationService

  Example	http://ed-fi-api-config:8081/connect/token
  Description	Token endpoint the Ed-Fi API forwards /oauth/token proxy requests to. Must use the container-network hostname in Docker deployments. Set via SELF_CONTAINED_OAUTH_TOKEN_ENDPOINT or KEYCLOAK_OAUTH_TOKEN_ENDPOINT

• ConfigurationServiceSettings:ClientSecret

  Example	(generated secret)
  Description	Client secret the Ed-Fi API uses to authenticate to the Configuration Service as the CMSReadOnlyAccess client. Must match the secret configured in the Configuration Service. Set via CONFIG_SERVICE_CLIENT_SECRET env var

Optional Settings

• AppSettings:MultiTenancy

  Default	false
  Description	When true, enables multi-tenancy mode. The tenant identifier is extracted from the URL route. See Single and Multi-Tenant Configuration

• AppSettings:RouteQualifierSegments

  Default	(empty)
  Description	Comma-separated list of route qualifier segments extracted from the URL path. Example: districtId,schoolYear. Segments must match dataStoreContexts configured in the Configuration Service. See Context-Based Routing for Year-Specific Data Store

• AppSettings:BypassTypeCoercion

  Default	false
  Description	When true, disables automatic type coercion on POST and PUT request values. Submitted values must already match the JSON Schema type. Improves performance but requires clients to submit correctly typed values

• AppSettings:AllowIdentityUpdateOverrides

  Default	(empty)
  Description	Comma-separated list of resource names that allow natural key (identity) updates. By default all resources reject identity updates with HTTP 400

• AppSettings:MaskRequestBodyInLogs

  Default	true
  Description	When true, masks request body content in DEBUG-level log statements by replacing all scalar values with "*". When false, the full unmasked body is logged. See Logging Configuration

• AppSettings:UseApiSchemaPath

  Default	false; Docker Compose env var USE_API_SCHEMA_PATH defaults to true in .env.example
  Description	When true, loads the API schema (core and extensions) from the directory specified by ApiSchemaPath. When false, loads the bundled schema from the application output

• AppSettings:ApiSchemaPath

  Default	(empty); Docker Compose env var API_SCHEMA_PATH defaults to /app/ApiSchema in .env.example
  Description	Directory containing bootstrap-api-schema-manifest.json and the declared schema files. Used when UseApiSchemaPath is true. Extension ApiSchema.json files placed in this directory are automatically loaded. See Extending with MetaEd

• AppSettings:DomainsExcludedFromOpenApi

  Default	(empty)
  Description	Comma-separated list of Ed-Fi domain names to exclude from the generated OpenAPI specification. Case-insensitive. Useful for reducing Swagger UI noise in focused deployments

• CacheSettings:ClaimSetsCacheExpirationSeconds

  Default	600
  Description	Seconds before cached claim sets (the claims taxonomy) expire and are re-fetched from the Configuration Service

• CacheSettings:ApplicationContextCacheExpirationSeconds

  Default	600
  Description	Seconds before cached application context expires and is re-fetched from the Configuration Service

• CacheSettings:TokenCacheExpirationSeconds

  Default	1500
  Description	Seconds before the cached Configuration Service access token expires and is renewed

• CacheSettings:ProfileCacheExpirationSeconds

  Default	1800
  Description	Seconds before cached profile definitions expire and are re-fetched from the Configuration Service

• CacheSettings:DataStoreCacheExpirationSeconds

  Default	600
  Description	Seconds before cached data store configuration expires and is re-fetched from the Configuration Service. Requires DataStoreCacheRefreshEnabled to be true. Set to 0 or a negative value to keep the cache until the next explicit reload

• CacheSettings:DataStoreCacheRefreshEnabled

  Default	true
  Description	Enables TTL-based automatic refresh of the cached data store configuration from the Configuration Service. When true, DMS re-fetches data store settings once a cache entry is older than DataStoreCacheExpirationSeconds, so changes made in the Configuration Service propagate without a restart. When false, the cached configuration is kept until the next explicit reload

• AppSettings:PathBase

  Default	(empty); Docker Compose env var PATH_BASE defaults to api in .env.example
  Description	URL path prefix for all Ed-Fi API endpoints. With PATH_BASE=api, resource endpoints are at /api/data/ed-fi/.... Leave empty to serve from the root path with no prefix

• DatabaseOptions:IsolationLevel

  Default	ReadCommitted
  Description	Transaction isolation level. Valid values from System.Data.IsolationLevel

• RateLimit:PermitLimit, RateLimit:Window, RateLimit:QueueLimit

  Defaults	5000, 10, 0
  Description	Fixed-window rate limiting, partitioned by hostname. PermitLimit requests are allowed per Window seconds. Excess requests queue up to QueueLimit (0 = no queuing); requests beyond the queue receive HTTP 429. Remove the RateLimit section entirely to disable rate limiting

---

Configuration Service Settings

Required Settings

• AppSettings:Datastore

  Example	postgresql
  Description	Primary database engine. Valid values: postgresql, mssql

• AppSettings:IdentityProvider

  Default	self-contained
  Description	Authentication provider. Valid values: self-contained (OpenIddict), keycloak. See Identity Provider

• DatabaseSettings:EncryptionKey

  Example	MySecretKey1234567890123456789012
  Description	AES key used to encrypt data store connection strings at rest. Must match ConfigurationServiceSettings:EncryptionKey in the Ed-Fi API. Set via DMS_CONFIG_DATABASE_ENCRYPTION_KEY environment variable. Recommended: a 32-character ASCII string

Optional Settings

• AppSettings:DeployDatabaseOnStartup

  Default	true
  Description	When true, creates and initializes the Configuration Service database on startup

• AppSettings:MultiTenancy

  Default	false
  Description	When true, enables multi-tenancy. The tenant identifier is extracted from the Tenant request header

• AppSettings:PathBase

  Default	(empty); Docker Compose env var DMS_CONFIG_PATH_BASE defaults to config in .env.example
  Description	URL base segment for all Configuration Service endpoints. Example: with PathBase=config, the management API is at /config/v3/vendors

• AppSettings:TokenRequestTimeoutSeconds

  Default	30
  Description	Timeout in seconds for outbound token requests

• AppSettings:ReverseProxy:UseForwardedHeaders

  Default	false
  Description	When true, respects X-Forwarded-* headers for URL generation. Enable when deploying behind a reverse proxy or load balancer

• AppSettings:ReverseProxy:KnownProxies

  Default	(empty)
  Description	Comma-separated list of trusted proxy IP addresses (e.g. 10.0.0.1,10.0.0.2). Restricts which proxies may supply forwarded-header values

• AppSettings:ReverseProxy:KnownNetworks

  Default	(empty)
  Description	Comma-separated list of trusted proxy CIDR networks (e.g. 192.168.1.0/24,10.0.0.0/8). Extends KnownProxies to cover a range of addresses

• AppSettings:EnableApplicationResetEndpoint

  Default	false
  Description	When true, enables PUT /v3/applications/{id}/reset-credential for resetting API client credentials via API. Disable when an application supports multiple API clients, as resetting credentials affects all clients for that application

• IdentitySettings:ClientSecretValidation:MinimumLength

  Default	32
  Description	Minimum length for client secrets registered with the Configuration Service. Secrets must also contain at least one uppercase letter, one lowercase letter, one number, and one special character from !@#$%^&*()-_=+[]{}:;,.?

• IdentitySettings:ClientSecretValidation:MaximumLength

  Default	128
  Description	Maximum length for client secrets