Configuration Reference

Konnektr Graph consists of two services — the API Service (REST API) and the Events Service (event streaming) — plus the Core SDK (AgeDigitalTwinsClient). Each reads configuration from appsettings.json, environment variables, or the .NET Aspire configuration system.

All configuration keys use the standard .NET configuration hierarchy. Environment variables use __ (double underscore) as a separator. For example, Parameters:TrackLastUpdatedBy becomes Parameters__TrackLastUpdatedBy.

API Service

The API Service (AgeDigitalTwins.ApiService) exposes the ADT-compatible REST API.

Connection Strings

The connection string must include the database host, port, credentials, and database name. The search path is automatically set to ag_catalog, "$user", public.

Npgsql Connection Pooling

Core SDK Options

These configure the AgeDigitalTwinsClient instance used internally.

Authentication

Authentication is disabled by default and must be explicitly enabled.

When enabled, the API validates JWT tokens using:

• Issuer validation (if Issuer is set)
• Audience validation
• Signing key validation
• MapInboundClaims = false (preserves original claim types)

Authorization

Requires Authentication:Enabled = true.

API Provider Options

When Authorization:Provider = Api, configure these under Authorization:ApiProvider:

When Api provider is used, the ClaimsPermissionProvider is also registered alongside the ApiPermissionProvider. Both are aggregated via CompositePermissionProvider — permissions from either source grant access.

CORS

Rate Limiting

Rate limiting is enabled by default. Controlled by Parameters:RateLimitingEnabled.

Global Rate Limit

Applies to all endpoints as a per-user/IP safety net.

Light Operations

Used for read operations (GET single items, list operations).

Medium Operations

Used for queries and batch operations.

Heavy Operations

Used for create/update/delete operations.

Admin Operations

Used for model management and job operations. Window is per-minute (not per-second).

Weighted Query (Token Bucket)

Used for the /query endpoint. Each query consumes tokens proportional to its query-charge.

Database Protection Middleware

Monitors and protects the database from overload. Controlled by Parameters:RateLimitingEnabled (the middleware only runs when rate limiting is enabled).

User ID Header Delegation

When Konnektr Graph runs behind an authenticating proxy (e.g., a proxy that validates Azure B2C tokens and forwards requests using a managed identity), the proxy can inject the original user's ID via an HTTP header. The API service uses this header value for authorization lookups and TrackLastUpdatedBy instead of the managed identity's claims.

When enabled, a UserIdHeaderMiddleware runs in the request pipeline after authentication and before authorization. It creates a synthetic ClaimsIdentity with the header value as the sub, NameIdentifier, and Name claims, then prepends it to the ClaimsPrincipal. Original managed identity claims (permissions, roles, scp) are copied to the synthetic identity so permission providers continue to work.

See Security for details.

Import Jobs

When jobs are enabled, blob storage services are registered for import/export of ND-JSON data:

• AzureBlobStorageService — Azure Blob Storage (SAS URIs)
• DefaultBlobStorageService — AWS S3, Google Cloud Storage, or local filesystem (routed by URI scheme)
• JobResumptionService — background service (IHostedService) that resumes interrupted import jobs on startup

OpenAPI / Scalar

Events Service

The Events Service (AgeDigitalTwins.Events) captures database changes via PostgreSQL logical replication (LISTEN/NOTIFY for telemetry) and routes them to configured sinks as CloudEvents.

Connection Strings

Falls back through this chain: GetConnectionString("agedb") → ConnectionStrings:agedb → AgeConnectionString.

Replication

Event Source / CloudEvents Source URI

TrackLastUpdatedBy

Event Sinks

Event sinks are configured under the EventSinks section. Each sink type supports multiple instances (configured as arrays).

Kafka

Configured under EventSinks:Kafka as an array.

MQTT

Configured under EventSinks:MQTT as an array.

Webhook

Configured under EventSinks:Webhook as an array.

NATS

Configured under EventSinks:NATS as an array.

Azure Data Explorer (Kusto)

Configured under EventSinks:Kusto as an array.

PostgreSQL / TimescaleDB

Configured under EventSinks:Postgres as an array.

The sink creates its tables (and the schema, when configured) on first use and, when the timescaledb extension is present, converts them to hypertables partitioned on time_stamp. See the PostgreSQL data history guide for schema details and temporal query examples.

Event Routes

Configured under EventRoutes as an array. Routes map event types to sinks.

SinkEventType Enum

EventFormat Enum

Dead Letter Queue

The Events Service maintains a dead letter queue table (digitaltwins_eventing.dead_letter_queue in the same PostgreSQL database) for events that fail to deliver after all retries.

Schema is automatically created on startup. No user configuration required.

Credential Resolution for Sinks

Credentials are resolved via CredentialFactory using this priority:

1. If TokenEndpoint + ClientId + ClientSecret are provided → GenericClientCredential (generic OAuth2)
2. If ClientId + ClientSecret are provided (with optional TenantId) → ClientSecretCredential (Azure AD)
3. If none of the above → DefaultAzureCredential (Azure-managed identity fallback)

Common Configuration

Both services use AddServiceDefaults() from AgeDigitalTwins.ServiceDefaults.

OpenTelemetry

OpenTelemetry is configured with:

• Metrics: ASP.NET Core instrumentation, HTTP client instrumentation, runtime instrumentation, custom meters (AgeDigitalTwins.SDK, AgeDigitalTwins.Events)
• Tracing: ASP.NET Core instrumentation, HTTP client instrumentation, custom sources (AgeDigitalTwins.SDK, AgeDigitalTwins.Events)
• Logging: OpenTelemetry logging with formatted messages and scopes

Health Checks

Both services expose:

• GET /health — All health checks pass (ready to accept traffic). Anonymous access.
• GET /alive — Only live-tagged checks pass (is the process alive?). Anonymous access.

API Service health checks:

• PostgreSQL connection (via Aspire Npgsql integration)

Events Service health checks:

• replication — AgeDigitalTwinsReplication.IsHealthy (tagged: live)
• event_sinks — All registered IEventSink.IsHealthy (tagged: live)

Logging

Standard ASP.NET Core logging configuration applies. Key namespaces for debugging:

Example Configuration

Minimal (No Authentication, No Event Sinks)

{
  "ConnectionStrings": {
    "agedb": "Host=localhost;Port=5432;Database=app;Username=app;Password=app"
  },
  "Parameters": {
    "AgeGraphName": "digitaltwins",
    "UseCnpgAge": true
  }
}

Full API Service with Auth and Rate Limiting

{
  "ConnectionStrings": {
    "agedb": "Host=localhost;Port=5432;Database=app;Username=app;Password=app"
  },
  "Parameters": {
    "AgeGraphName": "digitaltwins",
    "UseCnpgAge": true,
    "ModelCacheExpirationSeconds": 30,
    "MaxPoolSize": 50,
    "TrackLastUpdatedBy": true,
    "JobsEnabled": true,
    "RateLimitingEnabled": true,
    "GlobalPermitLimit": 500,
    "LightOperationsPermitLimit": 50,
    "HeavyOperationsPermitLimit": 10
  },
  "Authentication": {
    "Enabled": true,
    "Authority": "https://your-tenant.auth0.com/",
    "Audience": "api://konnektr-graph",
    "Issuer": "https://your-tenant.auth0.com/"
  },
  "Authorization": {
    "Enabled": true,
    "Provider": "Claims",
    "PermissionsClaimName": "permissions"
  },
  "Cors": {
    "Enabled": true,
    "AllowedOrigins": ["https://myapp.example.com"],
    "AllowedMethods": ["GET", "POST", "PUT", "DELETE"]
  }
}

Full Events Service with Kafka, Kusto, and NATS Sinks

{
  "ConnectionStrings": {
    "agedb": "Host=localhost;Port=5432;Database=app;Username=app;Password=app"
  },
  "Parameters": {
    "AgePublication": "age_pub",
    "AgeReplicationSlot": "age_slot",
    "MaxBatchSize": 100,
    "WalReceiverTimeoutSeconds": 30,
    "TrackLastUpdatedBy": true
  },
  "EventSinks": {
    "Kafka": [
      {
        "Name": "production-kafka",
        "BrokerList": "broker1:9092,broker2:9092",
        "Topic": "digitaltwins-events",
        "SaslMechanism": "PLAIN",
        "SaslUsername": "user",
        "SaslPassword": "pass",
        "SecurityProtocol": "SaslSsl"
      }
    ],
    "NATS": [
      {
        "Name": "realtime-nats",
        "Url": "nats://nats-cluster:4222",
        "Subject": "graph.events",
        "JetStream": true,
        "StreamName": "graph-events",
        "UseBinaryMode": true,
        "Token": "my-nats-token"
      }
    ],
    "Kusto": [
      {
        "Name": "archive-kusto",
        "IngestionUri": "https://ingest-cluster.kusto.windows.net",
        "Database": "DigitalTwinsHistory",
        "TenantId": "tenant-id",
        "ClientId": "sp-client-id",
        "ClientSecret": "sp-client-secret"
      }
    ],
    "Postgres": [
      {
        "Name": "PostgresDataHistory",
        "ConnectionString": "Host=postgres;Port=5432;Database=history;Username=graph;Password=graph",
        "Schema": "public",
        "TrackLastUpdatedBy": true
      }
    ]
  },
  "EventRoutes": [
    {
      "SinkName": "production-kafka",
      "EventFormat": "EventNotification",
      "TypeMappings": {
        "TwinCreate": "twin-created",
        "TwinUpdate": "twin-updated",
        "TwinDelete": "twin-deleted",
        "Telemetry": "twin-telemetry"
      }
    },
    {
      "SinkName": "realtime-nats",
      "EventFormat": "EventNotification"
    },
    {
      "SinkName": "archive-kusto",
      "EventFormat": "DataHistory"
    }
  ]
}

Environment Variable Reference

All configuration keys can be set as environment variables. The __ (double underscore) replaces : (colon) as the hierarchy separator.