Authaz.Sdk 0.3.4

Authaz.Sdk

Official .NET SDK for the Authaz Management API. Authentication, authorization, and identity management for your applications.

Install

dotnet add package Authaz.Sdk

Quickstart

using Authaz.Sdk;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddAuthazSdk(opts =>
{
    opts.BaseAddress = new Uri("https://api.authaz.com");
    opts.ApiKey      = "your-api-key";
});

var sp     = services.BuildServiceProvider();
var authaz = sp.GetRequiredService<IAuthazClient>();

// List users
var result = await authaz.Users.ListAsync();
if (result.IsSuccess)
    Console.WriteLine($"Found {result.Value!.Data.Count} users");

With ASP.NET Core

builder.Services.AddAuthazSdk(opts =>
{
    opts.BaseAddress = new Uri(builder.Configuration["Authaz:BaseUrl"]!);
    opts.ApiKey      = builder.Configuration["Authaz:ApiKey"];
});

// Inject IAuthazClient anywhere:
app.MapGet("/users", async (IAuthazClient authaz) =>
{
    var result = await authaz.Users.ListAsync();
    return result.IsSuccess ? Results.Ok(result.Value) : Results.Problem(result.Error!.Message);
});

Error handling

Every method returns AuthazResult<T> — a discriminated union that is either successful or a typed error. No exceptions for expected API failures.

var result = await authaz.Users.GetAsync(userId);

switch (result.Error)
{
    case null:
        Console.WriteLine(result.Value!.Email);
        break;
    case AuthazError.NotFound:
        Console.WriteLine("User not found");
        break;
    case AuthazError.Unauthorized:
        Console.WriteLine("Invalid API key");
        break;
    case AuthazError.Forbidden e:
        Console.WriteLine($"Permission denied: {e.Message}");
        break;
    case AuthazError.Validation e:
        foreach (var f in e.Fields)
            Console.WriteLine($"{f.Field}: {f.Message}");
        break;
    case AuthazError.RateLimited e:
        Console.WriteLine($"Rate limited — retry after {e.RetryAfter}");
        break;
    case AuthazError.Server e:
        Console.WriteLine($"Server error {e.StatusCode}: {e.Message}");
        break;
    case AuthazError.Network e:
        Console.WriteLine($"Network failure: {e.InnerException.Message}");
        break;
    case AuthazError.Canceled:
        Console.WriteLine("Operation was canceled");
        break;
}

Sub-clients

IAuthazClient exposes 8 top-level sub-clients:

Custom credential provider

Implement IAuthazCredentialProvider for non-API-key authentication (e.g. forwarding a user's bearer token from an HTTP context):

public sealed class MyCredentialProvider(IHttpContextAccessor ctx) : IAuthazCredentialProvider
{
    public ValueTask ApplyAsync(HttpRequestMessage request, CancellationToken ct)
    {
        var token = ctx.HttpContext?.Request.Cookies["access_token"];
        if (!string.IsNullOrEmpty(token))
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        return ValueTask.CompletedTask;
    }
}

// Registration:
services.AddAuthazSdk(opts => { opts.BaseAddress = ...; })
        .WithCredentials<MyCredentialProvider>();

Supported frameworks

net8.0 · net9.0 · net10.0 — AOT-compatible

License

MIT