Skip to main content

Configuration Fundamentals

This guide covers Endatix API configuration (appsettings.json and ConfigureEndatix()). It applies whether you installed from NuGet or from source.

Looking for Hub .env?

Endatix Hub is a Next.js app. Its keys live in Hub environment variables, not here.

Configuration Philosophy​

Endatix follows a configuration philosophy that balances ease of use with flexibility, offering three primary approaches:

1. Sensible Defaults Approach​

The simplest way to add Endatix to your application with pre-configured settings that work for most scenarios:

// Apply all defaults with minimal code
builder.Host.ConfigureEndatix();

Best for: Getting started quickly, proof-of-concept projects, or applications that don't need custom configuration.

2. Fully Customizable Approach​

For maximum control over every aspect of Endatix, configure only what you need:

// Configure only the components you need
builder.Host.ConfigureEndatix(endatix => {
    endatix.Persistence.UseSqlServer<AppDbContext>(o => o.ConnectionString = builder.Configuration.GetConnectionString("FormsDb")!);
    endatix.Security.UseJwtAuthentication();
});

Best for: Production applications with specific requirements, integrations with existing systems, or when you need fine-grained control.

3. Hybrid Approach (Defaults + Overrides)​

Start with sensible defaults and selectively customize only what you need:

// Start with defaults, then customize specific parts
builder.Host.ConfigureEndatixWithDefaults(endatix => {
    // Override specific components after applying defaults
    endatix.Security.WithCustomJwtAuthentication(options => {
        options.TokenValidationParameters.ValidateIssuer = false;
    });
});

Best for: Most production applications, balancing convenience with customization where needed.

Configuration Paradigms​

Endatix supports two main ways to provide configuration settings:

Code-Based Configuration​

Using the builder pattern in your Program.cs file provides a strongly-typed, fluent API for configuration:

builder.Host.ConfigureEndatix(endatix => {
    endatix.Persistence.UsePostgreSql<AppDbContext>(p => p.ConnectionString = builder.Configuration.GetConnectionString("PostgresFormsDb")!);
    endatix.Security.UseJwtAuthentication(options => {
        options.TokenValidationParameters.ValidateIssuer = false;
    });
});

Advantages:

  • Type safety with compiler checks
  • IntelliSense support in your IDE
  • Immediate validation of configuration options
  • Integration with dependency injection

File-Based Configuration​

Using appsettings.json files for configuration:

{
  "Endatix": {
    "ApplicationName": "My Endatix App",
    "Auth": {
      "Providers": {
        "EndatixJwt": {
          "SigningKey": "your-secure-key",
          "AccessExpiryInMinutes": 60,
          "Issuer": "endatix-api",
          "Audiences": ["endatix-hub", "endatix-client"]
        }
      }
    },
    "Data": {
      "ConnectionString": "Server=...;Database=...;",
      "EnableAutoMigrations": true
    }
  }
}

Advantages:

  • Configuration can be changed without recompiling
  • Environment-specific settings (using appsettings.Development.json, etc.)
  • Easier integration with configuration management tools
  • Support for configuration reloading during runtime

Most applications will use a combination of both paradigms, with code-based configuration referencing values from appsettings.json files.

Background processing​

Side effects such as webhook delivery run through Endatix background processing and the transactional outbox. Configure the in-process relay under Endatix:Outbox—see Background Processing for the pattern, defaults, and tuning options.

What's Next?​