Axowl.Sdk.Identity.Client 0.2.2

Axowl.Sdk.Identity.Client

Axowl SDK for B2B consumer apps to verify Axowl-issued EndUser JWTs and check permissions. Built on Axowl's v22 Snapshot Architecture (yes/no permission system).

Install

dotnet add package Axowl.Sdk.Identity.Client

Quickstart

using Axowl.Sdk.Identity.Abstractions.Contracts;
using Axowl.Sdk.Identity.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAxowlIdentity(opts =>
{
    opts.OrganizationSlug = "bullmark";              // your Axowl Org slug
    opts.Audience         = "app_bullmark_main";     // your ApplicationKey
    opts.ApiKey           = builder.Configuration["Axowl:ApiKey"]!;
    opts.Transport        = TransportMode.GrpcWithFallback;
    // Endpoints default to testapi/testgrpc.axowl.com — the environment Axowl serves today.
    // Set these only to point somewhere else:
    // opts.Authority         = "https://testapi.axowl.com";
    // opts.ServerAddress     = "https://testgrpc.axowl.com";
    // opts.RestServerAddress = "https://testapi.axowl.com";
    // The token issuer defaults to {Authority}/api/public/orgs/{OrganizationSlug} — what Axowl writes.
});

builder.Services.AddAuthorization();

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

// Protected endpoint — JWT verified via Axowl's JWKS, no server roundtrip
app.MapGet("/wallet", (HttpContext ctx) =>
{
    var p = ctx.User.GetAxowlPrincipal();
    return Results.Ok(new { user = p?.Email, org = p?.OrganizationId });
}).RequireAuthorization();

// Permission-gated endpoint — JWT claims fast-path. No token → 401, no permission → 403.
app.MapGet("/admin/billing",
    [RequirePermission("billing.admin")]
    () => Results.Ok("Sensitive billing data"));

// Same thing as an endpoint convention (also works on route groups)
app.MapGet("/reports/monthly", () => Results.Ok("Report"))
   .RequirePermission("report.monthly");

// Server-authoritative check — for cases where JWT claims may be stale
app.MapPost("/admin/wipe",
    [RequirePermission("system.admin", ServerCheck = true)]
    () => Results.Ok("Wiped"));

app.Run();

[RequirePermission] works on minimal APIs and on MVC controllers/actions. It is an authorization requirement that app.UseAuthorization() evaluates from endpoint metadata, so keep that call in the pipeline. AddAxowlIdentity registers the handler.

Upgrading from 0.2.1 or earlier. Three defects are fixed in 0.2.2: the default Issuer was "axowl" (no Axowl token carries it, so every real token got 401); the permissions claim was not parsed (every permission check got 403); and [RequirePermission] on a minimal-API handler was not enforced. If you set opts.Issuer = "axowl" as a workaround, remove it.

Two verification modes

Direct API client

For non-attribute use (programmatic checks, background jobs, audit):

public class WalletService
{
    private readonly IAxowlIdentityClient _identity;
    public WalletService(IAxowlIdentityClient identity) => _identity = identity;

    public async Task<bool> CanUserWithdrawAsync(string jwtToken, CancellationToken ct)
    {
        var result = await _identity.CheckPermissionAsync(jwtToken, "wallet.withdraw", ct);
        return result.Granted;
    }

    public async Task<AxowlPrincipal?> ResolveAsync(string jwtToken, CancellationToken ct)
    {
        var introspect = await _identity.IntrospectAsync(jwtToken, ct);
        return introspect.Active ? introspect.Principal : null;
    }
}

Permission scope format

The token carries permissions as one permissions claim holding a JSON-encoded string array (["wallet.read","report.*"]); ctx.User.GetAxowlPrincipal().Permissions is that list. Mirrors Axowl's v22 ResolvedScope:

Variables (:k=v) are matched as part of the resolved string. SDK's client-side wildcard handles prefix matching; full variable-aware evaluation requires ServerCheck = true.

Configuration reference

public sealed class AxowlIdentityClientOptions
{
    // JwtBearer / JWKS — required
    public string Authority         { get; set; } = "https://testapi.axowl.com";
    public string OrganizationSlug  { get; set; } = "";   // required
    public string Audience          { get; set; } = "";   // required (your ApplicationKey)
    public string? Issuer           { get; set; }         // null = {Authority}/api/public/orgs/{OrganizationSlug}

    // gRPC / REST IdentityService — optional, for server-side checks
    public string ServerAddress     { get; set; } = "https://testgrpc.axowl.com";
    public string RestServerAddress { get; set; } = "https://testapi.axowl.com";
    public string ApiKey            { get; set; } = "";   // required when using Introspect / CheckPermission
    public TransportMode Transport  { get; set; } = TransportMode.Grpc;
    public TimeSpan CallTimeout     { get; set; } = TimeSpan.FromSeconds(10);
}

Related

• Axowl.Sdk.Integrity.Client — hash chain / tamper detect
• Architecture: docs/2026-05-26-axowl-sdk-api-surface.md