Use the System API

The Guardhouse System API is a versioned /api/v1 surface for automating supported user, role, and permission operations. It is intended only for trusted backend services.

Administrative access

The system_api scope grants broad access to the tenant identity system. Never issue it to a browser or mobile client, expose its client secret, or forward its access token to an end user.

1. Configure a System API Client

Create a Backend / Service client in the Guardhouse dashboard, save its client ID and one-time client secret, then enable System API Access on that client.

Follow Configure System API Client for the dashboard steps and screenshots.

Use a separate client per service and environment. Store its secret in a server-side secret manager and rotate it if exposure is suspected.

2. Request a Token

Request the built-in system_api scope with client credentials:

curl -X POST "https://your-tenant.guardhouse.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_SYSTEM_API_CLIENT_ID" \
  -d "client_secret=YOUR_SYSTEM_API_CLIENT_SECRET" \
  -d "scope=system_api"

The request succeeds only when that confidential client is allowed to request the System API scope.

3. Call /api/v1

Send the resulting bearer token to an endpoint, for example:

curl "https://your-tenant.guardhouse.cloud/api/v1/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The published groups are:

• Users
• Roles
• Permissions

Use each endpoint page as the source of truth for its HTTP method, route, request body, and response.

.NET SDK

The official SDK can acquire and cache the token and register typed API clients in one call:

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

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

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

Protect your own /internal/roles route with appropriate application authorization; registering the Guardhouse client does not secure routes you expose.

Node.js SDK

The Node package includes an administrative client for supported user operations:

import { GuardhouseAdminClient } from "@guardhouse/node";

const guardhouse = new GuardhouseAdminClient({
  authority: "https://your-tenant.guardhouse.cloud",
  clientId: process.env.GUARDHOUSE_CLIENT_ID,
  clientSecret: process.env.GUARDHOUSE_CLIENT_SECRET,
});

const users = await guardhouse.listUsers({ page: 1, pageSize: 50 });

For roles, permissions, and endpoint-specific contracts, use the .NET typed clients or the documented HTTP endpoints unless the installed Node SDK version explicitly exposes the required operation.

Operational Rules

• Cache and reuse access tokens until renewal is necessary.
• Never log client secrets or access tokens.
• Apply timeouts and handle OAuth errors without exposing credentials in diagnostics.
• Revoke System API Access for clients that no longer need it.
• Audit administrative integrations and separate development, staging, and production credentials.