Monitoring and health
What RealmSSO records about your account, the API that reads it, the two health endpoints, and what we do not monitor.
We do not monitor the platform
We run no monitoring or alerting on the platform today. There is no status page. Nobody is paged when something fails.
This page covers two other things. It covers what RealmSSO records about your account. It also covers the health endpoints of the API.
Two kinds of record
RealmSSO keeps two kinds of record for each account. Do not mix them up. An observability event says what happened, how long it took and whether it failed.
The audit log says who changed what through the RealmSSO API. This page covers events. See Audit log for the audit log.
Observability events
Each event has an eventType, a status and an optional duration in milliseconds. A failed event can also carry an errorMessage. Each event belongs to one accountId. It can also name a connectionId.
RealmSSO writes these event types today.
| eventType | Recorded when |
|---|---|
| connection.health_check | Someone runs a connection check with POST /api/v1/connections/:id/test, in the dashboard or the API. The check runs on demand. No background schedule runs. |
| scim.provisioned, scim.updated, scim.deprovisioned | A SCIM client creates, updates or deletes a directory user. Deactivating a user records scim.updated. |
| scim.group_provisioned, scim.group_updated, scim.group_deprovisioned | A SCIM client creates, updates or deletes a directory group. |
| login.success | A user signs in through one of the account’s connections, and RealmSSO reads the sign-in from the realm. An IT admin who opens the Admin Portal with an invite link also records one. |
| login.failure | A sign-in through one of the account’s connections fails, and RealmSSO reads it from the realm. An invite link that is used or expired, presented without a portal session, also records one. |
SCIM writes record events. SCIM reads do not. RealmSSO writes each event in the background. A failed write is only logged. It never fails or delays the request that the event describes.
Sign-in events come from two writers
The Admin Portal records login.success and login.failure when an IT admin uses an invite link. RealmSSO also reads sign-in events from each account's realm. It does this about every 60 seconds.
So an event can be about a minute behind the sign-in. The delay can reach one poll interval. We have not measured it. RealmSSO is not on the browser login path, so it reads these events after the sign-in.
Dashboard totals are account-wide. The read routes filter only by accountId, eventType, status and since. They have no per-connection filter. loginRate is null, not a percentage, when the window holds no login events.
Connection health runs on demand
A connection check runs only when someone asks for it. It confirms that the connection's identity provider exists and is enabled. For a connection set up from a metadata URL, it reads the metadata again. It never performs a login. No scheduled check runs.
You run a check in the dashboard or the API. The Admin Portal cannot run one. A check records only healthy or down. RealmSSO never writes degraded.
For a SAML connection, a check shows when its certificate has expired or expires within 30 days. A check sends no alert.
Dashboard API
Four read routes accept a dashboard session or an API key. Each call reads one account, set by the accountId query parameter. No route shows more than one account.
A dashboard session needs a membership on that account. The viewer role is enough, because all four routes only read. An API key must belong to that account and carry the scope observability:read or *. Without either, the call returns 403. See Access control.
/api/v1/observability/statsCounts for a window, with a loginRate. The default window is the last 24 hours.
/api/v1/observability/eventsA paged feed of raw events. You can filter by eventType and status. A page holds up to 200 events.
/api/v1/observability/timelineCounts in hourly or daily buckets for one eventType, for charts. No dashboard screen shows them. API only.
/api/v1/observability/connection-healthEvery connection in the account, with a count of healthy, degraded, down and unknown. RealmSSO never writes degraded.
The dashboard shows one account at a time. For the account you pick, it shows sign-in counts, SCIM counts, a health summary and the 50 latest events.
One more route is outside this account-scoped group. GET /api/v1/observability/realm-co-residency is for platform operators only. It takes no accountId, and it refuses an API key. It shows any realm that holds more than one account.
Events are kept 90 days by default
RealmSSO purges events older than 90 days from its own database. The purge runs each time the sign-in event poll runs. The sign-in service expires its own event store on the same window. We did not measure this setting in production.
Retention does not purge the audit log. Nothing purges audit rows, and they are deleted with the account. Events carry an email address and an IP address. They outlast the account until the purge, up to 90 days.
Health endpoints
Two endpoints exist at the server root, not under /api/v1. They have different jobs.
| Endpoint | What it checks | Purpose |
|---|---|---|
| GET /health | Nothing. It shows only that the process is up. | Liveness |
| GET /readyz | The database and the Redis cache. If either is down, it returns 503. It also checks the sign-in service and reports it, but the status code does not depend on it. It reports the last webhook delivery pass. | Whether the API can serve requests |
The /readyz endpoint answers without authentication on api.realmsso.com. It is not a status page. It does not test a login. A sign-in service outage does not change its status code.
The platform does not stop sending traffic to an API instance when its database is down. It checks only that the process runs.
What we do not provide
There is no metrics endpoint
The API has no /metrics route. A Prometheus scrape of RealmSSO collects nothing.
Application logs are structured JSON on standard output. We do not ship them to a log platform or to you. How we run your instance has the list of what we do not have yet.