Skip to main content

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:

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.