ASP.NET Core

Overview

The Centinel middleware runs before your endpoints, sending request metadata to the validator API. The validator decides if the request should be allowed, blocked, redirected, or didn't match any protected path. Blocked or redirected responses return HTML from Centinel—bots never reach your application code.

Prerequisites

.NET SDK installed
NuGet package access
Centinel secret key (from the Dashboard)

Install

In your ASP.NET Core project:

dotnet add package Centinel.AspNetCore

Configure

Configuration

Add your Centinel settings to appsettings.json (or any other configuration provider):

{
  "CentinelConfiguration": {
    "SecretKey": "YOUR_SECRET_KEY",
    "ValidatorApiUrl": "https://validator.centinelanalytica.com/validate",
    "ProtectedPaths": ["/api", "/dashboard"],
    "ExcludedPaths": ["/health", "/static"],
    "FailOpen": true
  }
}

Property	Type	Required	Default	Description
`SecretKey`	`string`	Yes	–	Secret key for the validator API.
`ValidatorApiUrl`	`string`	No	`https://validator.centinelanalytica.com/validate`	Validator endpoint URL.
`ProtectedPaths`	`string[]`	No	–	Routes to validate. If empty, all routes are protected.
`ExcludedPaths`	`string[]`	No	–	Routes to skip validation on.
`FailOpen`	`boolean`	No	`true`	If `false`, block traffic when the Centinel API is unreachable.

Register services

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCentinel(builder.Configuration);
// Or configure manually:
// builder.Services.AddCentinel(options =>
// {
//     options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
//     options.ProtectedPaths = new() { "/api", "/admin" };
// });

var app = builder.Build();

Add middleware

Put the Centinel middleware in your request pipeline before endpoint execution:

app.UseRouting();
app.UseCentinel();
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

The middleware intercepts each request, calls the Centinel validator, and blocks or redirects suspicious traffic.

Middleware

With app.UseCentinel(), every matching request is validated automatically. Use ProtectedPaths and ExcludedPaths in your configuration to control which routes get checked.

Manual validation lets you apply Centinel only where you need it (e.g. sensitive APIs) without middleware-wide protection.

Custom validator endpoint

Override the validator URL or request timeout if you're using a self-hosted validator:

builder.Services.AddCentinel(options =>
{
    options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
    options.ValidatorApiUrl = "https://validator.yourdomain.com/validate";
    options.RequestTimeout = TimeSpan.FromSeconds(10);
});

Deployment notes

Make sure your production configuration or environment variables include the CentinelConfiguration values (especially SecretKey and any custom validator URL). Restart your app after updating keys so the middleware picks up the new settings.

Changelog

v1.0.1 — Response header passthrough

On this page