Identity-Based Access

June 9, 2026 · View on GitHub

Live demo | Access Mode Comparison

Overview

Simplest access mode. The resource verifies the agent's signature and applies its own access control. No Person Server, no token exchange. The resource decides based on WHO signed the request.

Sequence Diagram

sequenceDiagram
    participant Agent
    participant Resource
    Agent->>Resource: GET /data (signed, Signature-Key: sig=hwk, sig=jkt-jwt, or sig=jwks_uri)
    Resource->>Resource: Verify signature
    Resource-->>Agent: 200 OK (or 403 Forbidden)

Valid Signing Modes: hwk or jkt-jwt (pseudonymous) or jwks_uri (agent identity). NOT jwt — that requires a Person Server.

Code Example

Pseudonymous (`hwk`)

using AAuth.Crypto;
using AAuth;

var key = AAuthKey.Generate();

using var client = new AAuthClientBuilder(key)
    .UseHwk()
    .Build();

var response = await client.GetAsync("https://resource.example/data");
// 200 if resource's policy allows this key
// 403 if policy denies (signature valid, identity known, access denied)
// 401 if signature invalid (Signature-Error header explains why)

Agent Identity (`jwks_uri`)

using var client = new AAuthClientBuilder(key)
    .UseJwksUri("https://ap.example/.well-known/jwks.json", "key-1")
    .Build();

DI Registration

Pseudonymous (HWK)

using AAuth.Agent;
using AAuth.Crypto;

IKeyStore keyStore = FileKeyStore.Default();
var key = await keyStore.LoadAsync(configuration["AAuth:LocalKeyHandle"]!);

builder.Services.AddAAuthAgent("identity-hwk", options =>
{
    options.Key = key!;
});

Agent Identity (jwks_uri)

builder.Services.AddAAuthAgent("identity-jwks", options =>
{
    options.Key = key!;
    // No PersonServer → identity-only mode (no challenge handling)
});

Inject via IHttpClientFactory.CreateClient("identity-hwk"). See Dependency Injection for full reference.

Error Scenarios

Status	Signature-Error	Cause
401	`invalid_signature`	Signature doesn't verify
401	`unknown_key`	For jwks_uri: kid not found in JWKS
401	`unsupported_algorithm`	Key uses wrong algorithm (only EdDSA supported)
403	(none)	Signature valid but policy denies access