SDKs

Guardhouse provides official SDKs to help you integrate Guardhouse authentication into your client-side applications. The SDKs handle authentication, token management, and API calls to protected resources.

What SDKs Do

The Guardhouse SDKs are designed for client-side applications to:

✅ Authenticate Users - Handle login/logout flows
✅ Token Management - Get access tokens, refresh tokens, handle token lifecycle
✅ Token Validation - Validate JWT signatures or use token introspection
✅ Call Protected APIs - Make authenticated requests to your protected resources

What's SDKs Do NOT Do

The SDKs are NOT for:

❌ User Management (creating, updating, deleting users)
❌ Admin Operations (managing clients, applications, settings)

For user management and admin operations, use to User API with Client Credentials flow: User API Documentation

Available SDKs

SDK	Languages/Platforms	GitHub	Status
.NET SDK	C#, .NET 6.0+	View on GitHub	✅ Stable
Python SDK	Python 3.7+	Coming Soon	🚧
JavaScript SDK	Node.js, React, React Native	Coming Soon	🚧

Use Cases

1. Client Application (Requesting Access Tokens)

Use SDKs when your application needs to authenticate users and obtain access tokens to call protected APIs:

// .NET Example
using Guardhouse.SDK.Extensions;

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 = "openid profile email offline_access";
});

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

app.Run();

2. Resource Server (Protecting APIs)

Use SDKs when your API needs to validate tokens and authorize requests:

// .NET Example - Resource Server
using Guardhouse.SDK.Extensions;

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;
});

var app = builder.Build();

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

// Protected endpoint
app.MapGet("/api/protected", [Authorize] () =>
{
    return Results.Ok(new
    {
        Message = "This is protected data",
        Timestamp = DateTime.UtcNow
    });
});

app.Run();

3. Token Introspection (RFC 7662)

Use introspection for real-time token validation instead of JWT signature:

// .NET Example - Introspection
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";
});

Features

All Guardhouse SDKs provide:

✅ Authentication - Login/logout flows, authorization code handling
✅ Token Management - Get, cache, and refresh access tokens
✅ Token Validation - JWT signature validation or introspection
✅ Automatic Refresh - Seamless token renewal using refresh tokens
✅ PKCE Support - Authorization Code Flow with PKCE for SPAs
✅ Type Safety - Strongly typed models and responses
✅ Error Handling - Structured error handling and retry logic
✅ Logging - Built-in logging support
✅ Async Support - Non-blocking I/O operations
✅ HTTP Resilience - Built-in retry policies with exponential backoff

When to Use SDKs

Use SDKs for Client Applications

✅ Single Page Applications (React, Vue, Angular)

Need to authenticate users
Get access tokens
Call protected APIs

✅ Regular Web Applications (ASP.NET, Express.js)

Need to authenticate users
Get access tokens
Call protected APIs

✅ Native Applications (iOS, Android, Electron)

Need to authenticate users
Get access tokens
Call protected APIs

✅ Resource Servers (APIs, Microservices)

Need to validate tokens
Protect endpoints
Authorize requests

Use User API for User Management

✅ Backend Services that need to manage users

Create, update, delete users
Manage user profiles
Server-side admin operations

Use User API with Client Credentials flow: User API Documentation

Authentication Examples

Authorization Code Flow with PKCE

For SPAs and native/mobile applications:

// .NET Example
var loginResult = await tokenService.RequestTokenAsync(new AuthorizationCodeRequest
{
    Code = authorizationCode,
    RedirectUri = "https://app.example.com/callback",
    CodeVerifier = codeVerifier,
    State = state
});

var accessToken = loginResult.AccessToken;
var refreshToken = loginResult.RefreshToken;

Client Credentials Flow

For service-to-service (machine-to-machine) communication:

// .NET Example
var token = await tokenService.GetAccessTokenAsync();

Refresh Token Flow

Automatically refresh expired tokens:

// .NET Example - SDKs handle this automatically
var newAccessToken = await tokenService.RefreshTokenAsync(refreshToken);

Token Validation

JWT Signature Validation (Default)

Validates tokens using JWKS endpoint:

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

Token Introspection (RFC 7662)

Validates tokens via introspection endpoint for real-time revocation:

// .NET Example
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";
});

Configuration

.NET SDK Configuration

using Guardhouse.SDK.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseClient(options =>
{
    // Required
    options.Authority = "https://your_tenant.guardhouse.cloud";
    options.ClientId = "your-client-id";
    options.ClientSecret = "your-client-secret";
    options.Scope = "openid profile email offline_access";

    // Optional features
    options.EnableTokenCaching = true;
    options.EnableTokenRefresh = true;
    options.CacheExpirationBufferSeconds = 60;
    options.RequestTimeoutSeconds = 30;
    options.MaxRetryAttempts = 3;
});

var app = builder.Build();

Resource Server Configuration

using Guardhouse.SDK.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddGuardhouseResource(options =>
{
    // Required
    options.Authority = "https://your_tenant.guardhouse.cloud";
    options.Audience = "my_resource_api";

    // Validation mode: JWT Signature or Introspection
    options.ValidationMode = TokenValidationMode.JwtSignature;

    // Required for introspection mode
    options.IntrospectionClientId = "your-client-id";
    options.IntrospectionClientSecret = "your-introspection-client-secret";

    // JWT validation
    options.ValidateIssuer = true;
    options.ValidateAudience = true;
    options.ValidateLifetime = true;
    options.ValidAlgorithms = new[] { "RS256" };
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization(

What SDKs Do​

What's SDKs Do NOT Do​

Available SDKs​

Use Cases​

1. Client Application (Requesting Access Tokens)​

2. Resource Server (Protecting APIs)​

3. Token Introspection (RFC 7662)​

Features​

When to Use SDKs​

Use SDKs for Client Applications​

Use User API for User Management​

Authentication Examples​

Authorization Code Flow with PKCE​

Client Credentials Flow​

Refresh Token Flow​

Token Validation​

JWT Signature Validation (Default)​

Token Introspection (RFC 7662)​

Configuration​

.NET SDK Configuration​

Resource Server Configuration​