Clients, Resources, and Scopes

Clients, resources, and scopes answer three different questions:

Object	Question it answers	Example
Client	Who is requesting a token?	a React SPA or billing worker
API resource	Which API should accept the token?	orders API
Scope	What access is being requested?	orders.read

Clients

A client is an application registered with Guardhouse. Its configuration controls the flows, redirect URIs, resources, and scopes it may use.

Choose the client shape from where its code runs:

• Browser or other public client: cannot protect a secret. Use authorization code with redirect URIs. Never add a secret to the shipped application.
• Backend or service client: runs in a trusted server environment and can protect a secret. It may use client credentials for service-to-service calls.
• Server-side user application: can protect a secret but still redirects a user through the authorization code flow.

Redirect URIs must match the application URL exactly. Register development and production URLs explicitly instead of relying on a wildcard.

API Resources and Audiences

An API resource represents an API protected by Guardhouse. Its identifier is the audience that the API expects in access tokens.

For example, if an API is registered with the audience orders_api, configure its token middleware to require orders_api. A token meant for a different audience must be rejected even when it has a valid Guardhouse signature.

Use a stable, unique audience per security boundary. Frontend URLs, redirect URIs, and audiences are different values and should not be substituted for one another.

Scopes

A scope is a named unit of access a client can request. Examples in these guides use names such as orders.read; replace them with scopes registered in your tenant.

A requested scope is granted only when the client is allowed to request it. The receiving API should enforce the scope required by the operation, not just accept any valid token.

OpenID Connect scopes describe identity information:

• openid requests an OpenID Connect sign-in and ID token
• profile requests standard profile claims
• email requests email claims
• offline_access requests refresh-token access when the client is configured to use it

API scopes and identity scopes serve different purposes. An ID token or openid scope is not permission to call an API.

Scopes Versus Roles and Permissions

OAuth scopes describe delegated access carried by an access token. Guardhouse roles group permissions assigned to users. They can be used together, but they are not interchangeable.

Your API must define its own authorization rule. For example, a route may require orders.read, an administrator role, a particular permission claim, or a policy combining several checks.

The System API Scope

system_api is a built-in, high-privilege scope for the Guardhouse System API. It is not a general-purpose application scope. A backend client must have System API Access explicitly enabled before it can use it.

See Use the System API for the complete setup and security guidance.

Configuration Checklist

• The client type matches where the application runs.
• Redirect and logout URLs exactly match deployed application URLs.
• A browser client has no secret.
• Each API has a stable audience and validates it.
• The client is allowed only the resources and scopes it needs.
• The API enforces operation-specific authorization after token validation.