Troubleshooting

Start with the failing boundary: browser to Guardhouse, application to Guardhouse, API token validation, an external provider, or the Guardhouse runtime. Change one setting at a time and never include live tokens or secrets in screenshots or support messages.

Redirect URI rejected

Symptoms: authorization stops with an invalid or mismatched redirect URI.

1. Confirm the application is using the intended client ID.
2. Compare scheme, hostname, port, path, case, and trailing slash with the client's registered redirect URI.
3. Keep localhost only in a development client.
4. Confirm the application is not sending a logout URI as its login callback.

Do not solve a mismatch by registering a broad or attacker-controlled callback.

Browser reports a CORS error

1. Add the browser application's exact origin to Allowed origins.
2. Register an origin only as scheme, hostname, and port—not a callback path.
3. Confirm the failing response is actually a CORS failure; a 401 or 403 still requires authentication or authorization fixes.
4. Check the browser network response and reverse-proxy headers.

CORS does not grant access to an API and should not be used as an authorization control.

Client or grant is rejected

Use the flow supported by the client type:

Client	Supported use
SPA or Native	Authorization Code with PKCE; no client secret
Service	Client Credentials with a client secret

For an invalid-client error, verify the issuer, client ID, current service secret, and the environment. A secret copied before a rotation is no longer the current credential.

API returns 401

Check token validation in this order:

1. The token has not expired and the API host clock is correct.
2. The token issuer exactly matches the configured Guardhouse issuer.
3. The token audience matches the API resource audience.
4. The API is using the current signing keys from the resource's JWKS URL.
5. The allowed signing algorithm matches the resource details.
6. The request uses an access token, not an ID token.

Use Guardhouse discovery and resource-detail values. Do not construct issuer or key URLs from assumptions about the tenant hostname.

API returns 403

A 403 normally means the caller was authenticated but lacks required access.

• Confirm the client is assigned the resource and requested scope.
• Confirm the endpoint enforces the intended scope.
• For user actions, inspect the user's roles, inherited permissions, and direct permissions.
• Do not substitute System Access for an application permission.

Introspection reports an inactive token or fails authentication

• Confirm introspection is enabled for the resource.
• Use the current resource introspection client ID and secret.
• Do not use an application client's secret as the resource credential.
• Confirm the token belongs to the expected issuer.
• Treat an inactive result as denied access.

After rotating the introspection secret, update every API instance that performs introspection.

Refresh token stops working

Check whether:

• refresh tokens are enabled for the client;
• the refresh token or its authorization has expired or been revoked;
• the request uses the same client and issuer;
• the client was recreated or its policy changed;
• the user is blocked or no longer allowed to sign in.

Applications must return the user to an interactive login when refresh cannot safely continue.

Email is not delivered

1. Use Send test email on the active email provider.
2. Verify the sender address or domain with the provider.
3. Check provider suppression, sandbox, quota, and recipient rules.
4. Confirm the relevant Guardhouse template is active.
5. Check spam filtering and delivery delay.
6. Confirm the invitation, verification, recovery, or magic-link lifetime has not expired.

A successful provider test does not prove that a specific template or authentication flow is active.

Social login fails

• Confirm the provider is supported and enabled.
• Copy the Guardhouse callback value exactly into the provider configuration.
• Verify provider client credentials and application status.
• Check whether the provider allows the current tenant domain.
• Test with a new account and an existing linked account.

Update provider callbacks before activating a custom domain.

Passkey registration or login fails

• Use HTTPS outside local development.
• Confirm the browser and authenticator support the selected policy.
• Confirm platform or cross-platform authenticators are enabled as intended.
• Check challenge timeout and registration-attempt limits.
• Confirm the current hostname matches the expected relying-party identity.

After a domain change, an existing passkey may not be valid for the new relying-party identity. Test re-enrollment before requiring passkeys.

User cannot complete MFA

• Try an unused recovery code if backup codes are enabled.
• Confirm the device clock is correct for TOTP.
• Use administrator MFA reset only when it is enabled, authorized, and the user's identity has been verified.
• Review user activity after the reset.

Do not disable tenant-wide MFA as the first response to one account's recovery problem.

Storage or email provider test fails

• Re-enter credentials because saved secrets are intentionally hidden.
• Verify endpoint, region, bucket, sender, host, and port values.
• Confirm provider-side permissions and network access.
• Check whether credentials were rotated or revoked externally.
• For object storage, verify access to the exact private bucket.
• For SMTP, verify the provider's required transport and authentication policy.

Webhook delivery fails

1. Open the webhook delivery logs and inspect the response code.
2. Confirm the destination is reachable over HTTPS.
3. Validate the signature against the unmodified request body with the current secret.
4. Return success only after the event has been accepted for processing.
5. Make processing idempotent so retries do not duplicate work.

See Signature validation and Retries.

Self-hosted redirect loop or wrong HTTP scheme

Guardhouse processes forwarded protocol and client-address headers only from trusted proxies.

• Confirm the reverse proxy sends the forwarded protocol.
• Configure the proxy address or network as trusted.
• Confirm the public canonical domain is correct.
• Ensure TLS terminates at the expected layer.
• Test login and logout through the public hostname rather than a private application listener.

Self-hosted server does not start

Check:

• persistent database connectivity, credentials, permissions, and schema-update errors;
• cache connectivity and credentials;
• required tenant, domain, encryption, and provider settings;
• access to configured secret and runtime-configuration sources;
• application and container logs.

Use a database principal with only the permissions required by the supported deployment process, and test upgrades against a recoverable staging copy before production.

Interpret health checks correctly

An application health response can succeed while a data service or external provider is unavailable.

Monitor critical dependencies separately and use an end-to-end authentication smoke test after deployment.

Collect a safe diagnostic bundle

Include:

• occurrence time and timezone;
• public issuer and environment;
• client type, but not its secret;
• resource audience and requested scopes;
• HTTP status and sanitized error;
• relevant user-activity or webhook-log identifier;
• Guardhouse deployment version;
• recent proxy or deployment changes.

Never include passwords, API keys, client secrets, webhook secrets, cookies, authorization codes, or complete tokens.