---
title: "Auth Service Operations"
description: "Health checks, identity provider issues, and operational troubleshooting for Auth Service."
source: "Guardian Platform"
---
Auth Service issues usually appear as sign-in failures, authorization failures, missing membership, API key problems, service-account failures, or signing failures.

## Health Checks

`/health` is liveness only and `/health/ready` pings the database. `/health/auth` fetches the identity provider's JWKS and `/health/signing` checks OpenBao without signing; both require the Auth Service API secret (`API_SECRET`) as a bearer token:

```bash
curl https://guardian.example.com/authService/health
curl https://guardian.example.com/authService/health/ready
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/auth
curl -H "Authorization: Bearer $API_SECRET" \
  https://guardian.example.com/authService/health/signing
```

A ready response:

```json
{
  "status": "ready",
  "service": "auth-service",
  "database": "ok",
  "timestamp": "2026-10-16T12:00:00Z",
  "version": "1.2.1"
}
```

`/health/ready` and `/health/auth` return `503` with `"status": "not_ready"` when the database or identity provider is unreachable, and `401` on the authenticated probes for a missing or wrong secret. `/health/signing` returns `200` only for `ready`, or `not_supported` when the key-management provider is not OpenBao; `uninitialized`, `sealed`, `denied`, `unreachable`, `timeout`, `canceled`, `association_mismatch`, and `unavailable` return `503`.

## First Checks

- Confirm Auth Service is running and ready.
- Confirm it can reach the configured identity provider.
- Confirm platform services are configured to trust the same Auth Service.
- Confirm the user or integration has the expected membership and role.
- Confirm key-management access is available when signing workflows fail.

## Common Symptoms

- User can sign in but cannot open a project: check project membership.
- User cannot perform an action: check role permissions for the current project.
- API key fails: check whether the key was revoked, rotated, scoped differently than expected, or limited by `allowedIps` to other addresses.
- Service account fails: check operator-managed service-account configuration and secrets.
- Token exchange fails: confirm the deployment uses Keycloak or Microsoft Entra.

## Escalation Information

When escalating, include provider mode, affected user or service account, approximate time, impacted project, and the action that failed. Do not include raw tokens, API keys, or private key material.

## Related

- [RBAC and Membership](./rbac-and-membership.mdx) — checking membership and role assignments
- [API Keys and Service Accounts](./api-keys-and-service-accounts.mdx) — how scopes and project binding decide whether a key is refused
- [Token Exchange and Refresh Tokens](./token-exchange.mdx#troubleshooting) — fixes for token exchange and refresh failures
- [Key Configuration](./key-configuration.mdx#troubleshooting) — checks for signing failures, including OpenBao health
- [Identity Providers](./identity-providers.mdx) — the provider settings to confirm
- [Deployment Troubleshooting](../deployment/troubleshooting.mdx) — deployment-level sign-in checks