Tokens and Flows
Guardhouse supports authorization code, client credentials, and refresh-token flows. It also has a Guardhouse-specific passkey flow used by its authentication experience. Application integrations should select the standard flow that matches the caller.
Choose a Flow
| Caller | Flow | Why |
|---|---|---|
| Browser or interactive application | Authorization code with PKCE | Signs in a user through Guardhouse without collecting the user's password in the application |
| Backend service, worker, agent, or MCP server | Client credentials | Authenticates the service itself with a client ID and secret |
| An application renewing delegated access | Refresh token | Replaces an expired access token without another interactive sign-in, when enabled |
For a browser application, use a maintained OIDC SDK. Do not construct authorization requests or exchange codes by hand in application UI code.
Guardhouse does not support the implicit flow. Browser and native clients should use Authorization Code with PKCE.
Token Types
Access token
Send an access token to the API named by its audience:
Authorization: Bearer ACCESS_TOKEN
The API validates it and applies authorization policies. Do not send access tokens in query strings.
ID token
An ID token tells the client about the completed OpenID Connect sign-in. It is for the client application, not for authorizing API calls. An API must not accept an ID token in place of an access token.
Refresh token
A refresh token can obtain new tokens when the client and grant are configured for it. Keep it in storage appropriate to the application type and never expose it to unrelated services. Request offline_access only when the application genuinely needs background renewal.
Renewal behavior
When an access token expires:
- If refresh is configured and the refresh token is still valid, the SDK can request replacement tokens.
- If refresh is unavailable or rejected, clear stale authentication state and return the user to interactive sign-in.
Do not assume that every login produces a refresh token. Availability depends on the client type, requested scopes, and tenant configuration.
Tenant Endpoints
Guardhouse currently registers these endpoint paths:
| Purpose | Path |
|---|---|
| Start authorization | /connect/authorize |
| Exchange a code, request a service token, or refresh | /connect/token |
| Inspect token state | /connect/introspect |
| Revoke a token | /connect/revoke |
| Read OIDC user information | /connect/userinfo |
| End a Guardhouse session | /connect/logout |
Use the discovery document to obtain full URLs and supported metadata rather than concatenating paths in an SDK integration.
What an API Must Validate
At minimum, validate:
- signature or active state
- issuer, including its exact canonical form
- intended audience
- expiration and other lifetime constraints
- the scope, role, permission, or policy required by the operation
JWT signature validation performs the cryptographic checks locally. Introspection asks Guardhouse whether a token is active. Compare both approaches in Protect an API.