Authorization - Neuron Agent API

Authentication comes first

Authorization requirements only make sense once the router knows which authentication schemes it should advertise.

ControllerEndpointRouter Router = new ControllerEndpointRouter(
    "/api",
    true,
    new CamelCaseParameterNameCodec());

Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAccountsAuthenticationScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetLegalSignatureScheme());
Router.UseAuthenticationScheme(HttpAuthenticationSchemes.GetAnonymousScheme());

Those schemes operate at the router level. Authorization then decides what an authenticated caller is allowed to do on a given endpoint.

Two attributes, two jobs

Authorization is split into two parts:

[UseAuthorization] — turns on authorization middleware for a controller
[Authorization] — adds role or permission requirements to a specific method

Attribute-based authorization

[Controller]
[Route("/projects")]
[UseAuthorization(typeof(ProjectPermissionMiddleware))]
public sealed class ProjectsController : ControllerBase
{
    [HttpGet("/[projectId]")]
    [Authorization(Permission = "read:projects")]
    public Task<ProjectResponse> Get(string ProjectId)
    {
        return Task.FromResult(new ProjectResponse { ProjectId = ProjectId });
    }
}

public sealed class ProjectResponse
{
    public string ProjectId { get; set; } = string.Empty;
}

public sealed class ProjectPermissionMiddleware : AuthorizationMiddleware<PermissionAuthorizationRequirement>
{
    public override Task Authorize(AuthorizationContext Context, PermissionAuthorizationRequirement Requirement)
    {
        Context.Authorized = Context.HttpContext?.User is not null
            && Requirement.Permission == "read:projects";

        return Task.CompletedTask;
    }
}

Authorization middleware declared through [UseAuthorization] is constructed through Router.ServiceProvider, so constructor injection works there in the same way it does for controllers and middleware.

How the flow works

[UseAuthorization] registers one or more controller-level authorization middleware types
[Authorization] adds requirements to individual methods
AuthorizationMiddleware<T> only receives requirements of type T
The middleware must set AuthorizationContext.Authorized = true
Rejected requirements return 403 Forbidden

You can apply [UseAuthorization] more than once to the same controller when different requirement types should be evaluated by different middleware classes.

Roles and permissions together

[Controller]
[Route("/admin")]
[UseAuthorization(typeof(ProjectPermissionMiddleware))]
[UseAuthorization(typeof(AdminRoleMiddleware))]
public sealed class AdminController : ControllerBase
{
    [HttpGet("/dashboard")]
    [Authorization(Permission = "read:projects")]
    [Authorization(Role = "Administrator")]
    public Task<DashboardResponse> Get()
    {
        return Task.FromResult(new DashboardResponse { Message = "authorized" });
    }
}

Low-level equivalent

Router.UseAuthorization("/projects");
Router.RegisterMiddleware("/projects", new ProjectPermissionMiddleware().Invoke);
Router.SetAuthorization(
    HttpMethodType.Get,
    "/projects/[projectId]",
    new PermissionAuthorizationRequirement("read:projects"));

When to choose attributes vs manual setup

Choose attributes when:

The route is already controller-based
The requirement belongs naturally to one endpoint
You want the policy close to the action method

Choose the manual API when:

You register low-level endpoints directly
You need fine-grained control over pipeline wiring
You build a reusable router module outside controller discovery

For intentional HTTP failures inside authorization or middleware, throw HttpException subclasses such as ForbiddenException. Unexpected exceptions are converted into 500 responses by the router’s exception boundary.

What to read next

Advanced patterns covers raw request handling, manual endpoints, and parameter-name codecs.

​Authentication comes first

​Two attributes, two jobs

​Attribute-based authorization

​How the flow works

​Roles and permissions together

​Low-level equivalent

​When to choose attributes vs manual setup

​What to read next

Authentication comes first

Two attributes, two jobs

Attribute-based authorization

How the flow works

Roles and permissions together

Low-level equivalent

When to choose attributes vs manual setup

What to read next