Tharga.Team.Service 3.0.3

Tharga Team Service

Server-side API-key authentication, authorization enforcement, controller registration, OpenAPI/Swagger setup, and audit logging for ASP.NET Core projects. Targets .NET 9.0 and .NET 10.0.

Features

• API key authentication - Reads the X-API-KEY header, validates against a store, and populates TeamKey, AccessLevel, and scope claims.
• Access level authorization - AccessLevelProxy<T> enforces [RequireAccessLevel] on service methods via DispatchProxy.
• Scope authorization - ScopeProxy<T> enforces [RequireScope] with audit logging.
• Controller + Swagger registration - Single-call setup for MVC controllers, OpenAPI document with API key security scheme, and Swagger UI.
• API key management - Default MongoDB-backed ApiKeyAdministrationService with key hashing. Configurable via ApiKeyOptions — see API key options.
• Audit logging - CompositeAuditLogger with ILogger and MongoDB backends. ⚠️ Stores to ILogger only by default — see Audit logging.
• API-key lifecycle hook - Capture the private token on create/recycle (plus a delete signal) via IApiKeyLifecycleHandler — see Capturing the private token.
• Pluggable - Implement IApiKeyAdministrationService (from Tharga.Team) to bring your own storage backend.

Quick start

using Tharga.Team;
using Tharga.Team.Service;

// Program.cs
builder.Services.AddThargaControllers();
builder.Services.AddAuthentication()
    .AddThargaApiKeyAuthentication();
builder.Services.AddThargaApiKeys();

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

System API keys

For infrastructure-level credentials that aren't tied to a team (MCP gatekeepers, CI/CD callers, cross-team admin tooling), use system keys — API keys with no TeamKey.

Create and manage them via the <SystemApiKeyView /> component in Tharga.Team.Blazor (gated by the Developer role), or programmatically via IApiKeyAdministrationService.CreateSystemKeyAsync(name, scopes, expiryDate, createdBy).

System keys authenticate through the same X-API-KEY header. The principal they produce carries the IsSystemKey=true claim and the explicit scopes granted at creation time — no TeamKey claim.

Protect system-only endpoints with the system policy:

app.UseThargaMcp().RequireAuthorization(ApiKeyConstants.SystemPolicyName);

The two policies are mutually exclusive: ApiKeyPolicy rejects system keys, SystemApiKeyPolicy rejects team keys.

Team API keys

Protect endpoints with the built-in policy:

[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 });
    }
}

Enforce access levels on services:

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

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

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

API key options

API key behaviour is configured via ApiKeyOptions (passed to AddThargaApiKeyAuthentication, or o.ApiKey under AddThargaPlatform):

Audit logging

AddThargaAuditLogging records mutations (team-service operations and API-key management) and authorization events via CompositeAuditLogger.

builder.Services.AddThargaAuditLogging(o =>
{
    o.StorageMode = AuditStorageMode.MongoDB;   // see gotcha below
    o.RetentionDays = 90;                       // null (or <= 0) = keep forever
});

⚠️ Gotcha: StorageMode defaults to Logger only, so the MongoDB-backed AuditLogView stays empty until you set AuditStorageMode.MongoDB (or Logger | MongoDB). AuditStorageMode is a [Flags] enum.

See the implementation guide for the full reference.

Capturing the private token

The private token is shown once and never persisted, logged, or exposed over an API. To capture it (e.g. to re-deliver a minted key), register an IApiKeyLifecycleHandler — it receives the token on create and recycle/regenerate, plus a tokenless delete signal:

public class MyHandler(ISecretProtector protector, IMyStore store) : IApiKeyLifecycleHandler
{
    public Task OnApiKeyLifecycleAsync(ApiKeyLifecycleContext ctx) => ctx.Reason switch
    {
        ApiKeyLifecycleReason.Deleted => store.RemoveAsync(ctx.ApiKeyId),
        _ => store.SaveAsync(ctx.ApiKeyId, protector.Protect(ctx.PrivateToken), ctx.TeamKey, ctx.Tags),
    };
}

builder.AddThargaPlatform(o => o.AddApiKeyLifecycleHandler<MyHandler>());

A throwing handler propagates out of the originating operation (capture failures are not swallowed). You own whatever you capture — encrypt it at rest.

Dependencies

• Tharga.Team - Domain models, authorization primitives, and service abstractions.
• Tharga.MongoDB - MongoDB repository infrastructure.
• Tharga.Toolkit - Shared utilities including API key hashing.
• Swashbuckle.AspNetCore - Swagger UI generation.

Related packages

Links

• GitHub repository
• Report an issue