Quickstart — .NET (Authaz.Sdk) - Authaz

Quickstart — .NET (Authaz.Sdk) - Authaz - Docs

// Program.cs
using Authaz.Sdk;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddAuthazSdk(opts =>
{
    opts.BaseAddress = new Uri("https://your-app.authaz.io");
    opts.ApiKey = builder.Configuration["AUTHAZ:APIKEY"];
});
 
var app = builder.Build();

app.MapGet("/users/{id:guid}", async (Guid id, IAuthazClient authaz) =>
{
    var result = await authaz.Users.GetAsync(id);
    return result.IsSuccess
        ? Results.Ok(result.Value)
        : Results.Problem(result.Error!.Message, statusCode: 500);
});

var result = await authaz.Users.GetAsync(userId);
 
if (result.IsSuccess)
{
    var user = result.Value!;
    Console.WriteLine($"{user.Email} — {user.Status}");
}
else
{
    // Error is a discriminated union
    var problem = result.Error switch
    {
        AuthazError.NotFound nf      => Results.NotFound(nf.Message),
        AuthazError.Unauthorized     => Results.Unauthorized(),
        AuthazError.Forbidden f      => Results.Forbid(),
        AuthazError.Validation v     => Results.ValidationProblem(
            v.Fields.ToDictionary(f => f.Field, f => new[] { f.Message })),
        AuthazError.RateLimited r    => Results.Problem(
            r.Message, statusCode: 429),
        AuthazError.Server s         => Results.Problem(
            s.Message, statusCode: s.StatusCode),
        AuthazError.Network n        => Results.Problem(
            "Authaz unreachable", statusCode: 503),
        _                            => Results.Problem(result.Error!.Message),
    };
}

authaz.Users           // List, get, suspend, activate, sessions, MFA reset
authaz.Applications    // List, create, update, stats, custom domains
authaz.Tenants         // List, create, update, per-tenant OAuth config
authaz.Authorization   // .Roles, .Policies, .Permissions.CheckAsync
authaz.Invitations     // Send, list, resend, revoke, pending count
authaz.Email           // Email provider config + templates
authaz.Auth            // API keys, OAuth credentials
authaz.Audit           // Trail logs (search + list)

Symptom	Likely cause	Fix
Every call returns `AuthazError.Unauthorized` (401)	API key wrong, missing, or you used an OAuth Client Secret instead.	Management API needs the key from Settings → API Keys → Management (`mgmt_01h...`), not the Client Secret.
`AuthazError.Network` on every call	Wrong `BaseAddress`, no internet, or DNS / firewall issue.	Confirm `BaseAddress` is `https://your-app.authaz.io` and the host is reachable.
`result.Value` is `null` after `IsSuccess`	You're checking `IsSuccess` for an endpoint that returns no body (e.g. delete).	Use the bool result; `Value` is only populated on endpoints that return data.
`AuthazError.NotFound` for an ID you just created	You're scoped to the wrong tenant or organization.	If multi-tenant, pass the correct tenant ID; verify the ID belongs to the same org as the API key.
DI throws `Unable to resolve service for IAuthazClient`	`AddAuthazSdk` not called or called after `Build()`.	Register before `var app = builder.Build();`.

app.MapPost("/can/{permission}", async (
    string permission,
    [FromBody] CheckBody body,
    IAuthazClient authaz) =>
{
    var result = await authaz.Authorization.Permissions.CheckAsync(
        new CheckPermissionRequest(
            UserId: body.UserId,
            Permission: permission,
            TenantId: body.TenantId?.ToString()));
 
    return result.IsSuccess
        ? Results.Ok(new { allowed = result.Value!.Allowed })
        : Results.Problem(result.Error!.Message);
});
 
record CheckBody(string UserId, Guid? TenantId = null);

Quickstart — .NET (Authaz.Sdk)

Prerequisites#

Step 1 — Install

Step 2 — Register the SDK#

Step 3 — Use the client#

Step 4 — Handle the result#

Step 5 — What's on the client#

Step 6 — Run it#

If something's wrong#

Worked example — authorization check#

Customizing the credential provider#

Adding handlers#

Complete worked example#

Next steps#