Tharga.Api 0.0.1-pre.5

Tharga Api

Reusable API-key authentication, authorization, controller registration, and OpenAPI/Swagger setup for ASP.NET Core projects. Targets .NET 9.0 and .NET 10.0.

Features

• API key authentication – AuthenticationHandler that reads the X-API-KEY header, validates it against a store, and populates TeamKey, Name, and AccessLevel claims.
• Access level authorization – [RequireAccessLevel] attribute with AccessLevelProxy<T> for declarative, service-level authorization enforcement via DispatchProxy.
• Controller registration – AddThargaControllers registers MVC controllers, OpenAPI document generation (with API key security scheme), Swagger UI, and endpoints API explorer in a single call.
• API key management – IApiKeyAdministrationService provides key lookup, listing, refresh, and lock operations. A default MongoDB-backed implementation is included.
• Pluggable storage – Implement IApiKeyAdministrationService to use your own data store, or use the built-in ApiKeyAdministrationService with Tharga.MongoDB.

Getting started

1. Install the package

dotnet add package Tharga.Api

2. Register controllers and authentication

// Program.cs
builder.Services.AddThargaControllers(o =>
{
    o.SwaggerTitle = "My API v1";
});

builder.Services.AddAuthentication()
    .AddThargaApiKeyAuthentication();

// If using the built-in MongoDB key store:
builder.Services.AddThargaApiKeys();

3. Map controllers and Swagger

var app = builder.Build();
app.UseThargaControllers();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

4. Protect endpoints

[Authorize(Policy = ApiKeyConstants.PolicyName)]
[ApiController]
[Route("api/[controller]")]
public class MyController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        var teamKey = User.FindFirst(TeamClaimTypes.TeamKey)?.Value;
        return Ok(new { teamKey });
    }
}

5. Access level enforcement on services

Decorate service interface methods with [RequireAccessLevel] and register with AddScopedWithAccessLevel:

public interface IMyService
{
    [RequireAccessLevel(AccessLevel.Viewer)]
    IAsyncEnumerable<Item> GetAsync();

    [RequireAccessLevel(AccessLevel.User)]
    Task<Item> AddAsync(string name);

    [RequireAccessLevel(AccessLevel.Administrator)]
    Task DeleteAsync(string key);
}

// Program.cs
builder.Services.AddScopedWithAccessLevel<IMyService, MyService>();

The proxy reads TeamKey and AccessLevel claims from HttpContext.User. Methods without the attribute throw InvalidOperationException (fail-closed).

6. API key access level

The AccessLevel for API keys is determined by:

• ApiKeyEntity.AccessLevel field (stored on the entity). If null (legacy keys), defaults to Administrator for backwards compatibility.
• IApiKey.Tags["AccessLevel"] fallback (custom implementations). If not set, defaults to Viewer (fail-closed).
• Auto-created keys in simple mode get User access level.

The access level hierarchy is:

7. Custom key service (optional)

To use your own storage backend, implement IApiKeyAdministrationService and register it:

builder.Services.AddAuthentication()
    .AddThargaApiKeyAuthentication<MyCustomKeyService>();

Public API

Dependencies

• Tharga.MongoDB – MongoDB repository infrastructure and auto-registration.
• Tharga.Toolkit – Shared utilities including API key hashing.
• Swashbuckle.AspNetCore – Swagger UI generation.