OIDC and OAuth Endpoints

Guardhouse is an OpenID Connect provider and OAuth 2.0 authorization server. Replace AUTHORITY below with your tenant issuer, such as https://your-tenant.guardhouse.cloud.

Discover Metadata First

GET AUTHORITY/.well-known/openid-configuration

Discovery is the source of truth for the issuer, endpoint URLs, supported grants, signing algorithms, and jwks_uri. Use those returned values instead of constructing a JWKS URL.

The server normalizes its issuer with a trailing slash. Token validators must compare the issuer exactly as advertised by discovery.

Endpoint Summary

Method and path	Purpose	Caller authentication
GET /.well-known/openid-configuration	Provider discovery metadata	Public
GET {jwks_uri}	Current public signing keys	Public; obtain the URI from discovery
GET /connect/authorize	Begin interactive authorization	Browser session and registered client
POST /connect/token	Exchange a code, refresh token, or client credentials	Client rules depend on the registered client type
GET or POST /connect/userinfo	Return claims allowed by the token's scopes	Bearer access token
POST /connect/introspect	Report whether a token is active and return allowed metadata	Configured introspection credentials
POST /connect/revoke	Revoke an access or refresh token	Registered client authentication where required
GET or POST /connect/logout	End the Guardhouse browser session	Browser session; standard logout parameters may apply

The revocation path is /connect/revoke, not /connect/revocation.

Supported Grants

The server registers:

• Authorization Code for interactive user authentication
• Client Credentials for service identities
• Refresh Token for renewing delegated sessions
• the Guardhouse-specific passkey grant urn:guardhouse:params:oauth:grant-type:passkey

Public browser and native clients should use Authorization Code with PKCE. The custom passkey grant is an SDK/Guardhouse UI integration point; do not hand-code it as a replacement for the hosted login flow.

Scopes

Guardhouse registers these protocol/system scopes:

• openid, profile, email, and roles
• offline_access for refresh-token requests
• system_api for the external user, role, and permission API
• passkeys for Guardhouse passkey flows

Tenant API resources add their own scopes. A requested custom scope must exist, be allowed for the client, and map to an API resource. That resource supplies the token audience.

Client Credentials Example

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=system_api

This request succeeds only when the backend client has System API Access enabled. Keep the secret in trusted server-side storage.

Token Lifetimes

Current server defaults are:

Token	Default lifetime
Access token	1 hour
Refresh token	14 days

A client can have its own configured access- or refresh-token lifetime. Always use expires_in and token claims at runtime instead of hard-coding these defaults.

Security Rules

• Require HTTPS outside local development.
• Use PKCE for public browser and native clients.
• Validate issuer, audience, signature, expiry, and required scopes at API boundaries.
• Load signing keys through the discovery document's jwks_uri and allow for key rotation.
• Use introspection credentials only on the resource server they protect.
• Revoke and rotate a credential immediately after suspected exposure.
• Do not send the high-privilege system_api scope to a browser or mobile client.

Protocol failures use OAuth-style error fields. See Errors and limits.