Skip to main content
Start Free Trial

.NET SDK

Official .NET SDK for Guardhouse.

Use it to:

  • request access tokens with client credentials
  • validate incoming access tokens in your API
  • call the Guardhouse System API for users, roles, and permissions

Install​

dotnet add package Guardhouse.SDK

Package: Guardhouse.SDK
Repository: github.com/legiosoft/guardhouse-sdk-dotnet

Supported frameworks:

  • .NET 6.0
  • .NET 7.0
  • .NET 8.0
  • .NET 9.0
  • .NET 10.0

What The SDK Includes​

  • IGuardhouseTokenService for access token acquisition, refresh, and introspection
  • IGuardhouseResourceService for resource-server token validation
  • IGuardhouseUsersClient for System API user operations
  • IGuardhouseRolesClient for System API role operations
  • IGuardhousePermissionsClient for System API permission operations
  • DI registration helpers for token client, resource server, and System API clients

Backward-compatible aliases are still available for older integrations:

  • IGuardhouseUserService
  • AddGuardhouseUserClients(...)
  • AddGuardhouseClientWithUserClients(...)

Call The System API​

Before using the System API, configure a System API client in Guardhouse and obtain its credentials:

One-Call Setup​

Use this when the same application both requests machine-to-machine tokens and calls the Guardhouse System API.

using Guardhouse.SDK.Constants;
using Guardhouse.SDK.Extensions;
using Guardhouse.SDK.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseClientWithApiClients(
    authority: "https://your-tenant.guardhouse.cloud",
    clientId: "YOUR_SYSTEM_API_CLIENT_ID",
    clientSecret: "YOUR_SYSTEM_API_CLIENT_SECRET",
    scope: AuthorizationConsts.Scopes.SystemApi,
    apiBaseUrl: "https://your-tenant.guardhouse.cloud");

var app = builder.Build();

app.MapGet("/example/roles", async (IGuardhouseRolesClient rolesClient) =>
{
    var roles = await rolesClient.GetRolesAsync();
    return Results.Ok(roles);
});

app.Run();

Guardhouse .NET SDK registration helpers are safe to call multiple times.

Split Setup​

Use this when token configuration is already registered elsewhere and you only need to add the typed System API clients.

using Guardhouse.SDK.Constants;
using Guardhouse.SDK.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseClient(options =>
{
    options.Authority = "https://your-tenant.guardhouse.cloud";
    options.ClientId = "YOUR_SYSTEM_API_CLIENT_ID";
    options.ClientSecret = "YOUR_SYSTEM_API_CLIENT_SECRET";
    options.Scope = AuthorizationConsts.Scopes.SystemApi;
});

builder.Services.AddGuardhouseApiClients(options =>
{
    options.ApiBaseUrl = "https://your-tenant.guardhouse.cloud";
});

AddGuardhouseClient(...) and AddGuardhouseApiClients(...) add the SDK's internal infrastructure once, while later configuration delegates still apply option values.

System API Client Behavior​

  • Create operations return typed response DTOs
  • Read operations return a typed DTO, or null when the server returns 404 Not Found
  • Update and action operations return true on success and false on 404 Not Found
  • Other non-success responses throw InvalidOperationException
  • ApiBaseUrl falls back to Authority when it is not set

Request Access Tokens​

Use AddGuardhouseClient(...) when your service needs a token client without the System API clients.

using Guardhouse.SDK.Extensions;
using Guardhouse.SDK.Services;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseClient(options =>
{
    options.Authority = "https://your-tenant.guardhouse.cloud";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.Scope = "api";
    options.EnableTokenCaching = true;
});

var app = builder.Build();

app.MapGet("/token", async (IGuardhouseTokenService tokenService) =>
{
    var accessToken = await tokenService.GetAccessTokenAsync();
    return Results.Ok(new { access_token = accessToken });
});

app.Run();

AddGuardhouseClient(...) is safe to call multiple times from shared startup code or tests.

Optional Refresh Tokens​

If your Guardhouse setup issues refresh tokens, enable them explicitly:

builder.Services.AddGuardhouseClient(options =>
{
    options.Authority = "https://your-tenant.guardhouse.cloud";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.Scope = "api";
    options.EnableTokenRefresh = true;
    options.IncludeOfflineAccessScope = true;
});

Protect An API​

Use AddGuardhouseResource(...) when your application receives bearer tokens and needs to validate them.

using Guardhouse.SDK.Extensions;
using Guardhouse.SDK.Models;
using Microsoft.AspNetCore.Authorization;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseResource(options =>
{
    options.Authority = "https://your-tenant.guardhouse.cloud";
    options.Audience = "my_resource_api";
    options.ValidationMode = TokenValidationMode.JwtSignature;
});

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet(
    "/api/protected",
    [Authorize(AuthenticationSchemes = "Guardhouse")] () => Results.Ok("Protected data"));

app.Run();

AddGuardhouseResource(...) is safe to call multiple times when resource-server wiring is composed from multiple modules.

Introspection Mode​

Use introspection when you want token validation to call Guardhouse directly instead of validating JWT signatures locally.

using Guardhouse.SDK.Models;

builder.Services.AddGuardhouseResource(options =>
{
    options.Authority = "https://your-tenant.guardhouse.cloud";
    options.Audience = "my_resource_api";
    options.ValidationMode = TokenValidationMode.Introspection;
    options.IntrospectionClientId = "your-introspection-client-id";
    options.IntrospectionClientSecret = "your-introspection-client-secret";
    options.IntrospectionCredentialTransmission = IntrospectionCredentialTransmission.FormData;
});

Main Registration Helpers​

  • AddGuardhouseClient(...)
  • AddGuardhouse(...)
  • AddGuardhouseApiClients(...)
  • AddGuardhouseClientWithApiClients(...)
  • AddGuardhouseResource(...)

Configuration Notes​

Repeated Registration Safety​

  • Guardhouse .NET SDK registration helpers are safe to call multiple times.
  • The SDK adds its internal infrastructure once, while later configuration delegates still apply option values.
  • This supports scenarios where registration may happen in shared startup code, tests, or feature-specific wiring.

Shared Startup And Tests​

If your application builds service registration from shared bootstrap code, feature modules, or test hosts, you do not need extra guards around Guardhouse registration. Existing code does not need to change.

Troubleshooting​

Registration code runs more than once​

If Guardhouse setup executes from more than one startup path, you can keep the repeated calls. The SDK avoids duplicate internal registrations and continues applying later option configuration.

API Endpoint Examples​

The API reference includes endpoint examples for the supported System API surface. When a typed SDK helper is available, the endpoint page shows the SDK call; otherwise, use the documented HTTP contract.

Users​

Roles​

Permissions​

Notes​

  • Use AuthorizationConsts.Scopes.SystemApi for System API integrations.
  • The SDK System API surface is currently limited to users, roles, and permissions.
  • If you only need endpoint-specific examples, the API reference pages above are the best source because they show the route, request contract, and SDK snippet together.