Audit log
The audit log records changes made through the RealmSSO API, best effort. This page says what it holds, who can read it, how long rows last, and what it leaves out.
In short
- Each account has its own audit log. A row records who acted, what they did, and on which resource.
- The log covers changes made through the RealmSSO API.
- Writes are best effort. An action can succeed with no audit row.
- The log is a plain database table. Nothing detects a later change to a row.
- User sign-ins, SCIM syncs and Admin Portal sign-ins are events, not audit rows.
- Dashboard sign-ins are not audit rows, and they are not events.
- Changes made directly in the sign-in service, outside the API, are not in the log.
- Every member of the account, from viewer up, can read the log. It has no export and no streaming.
- RealmSSO keeps the rows while the account exists and deletes them with the account.
The fields
Each row belongs to one account. The fields are:
| Field | Meaning |
|---|---|
actorType | "vendor" | "customer_admin" | "system" | "api_key" | "agent". vendor is a dashboard user. customer_admin is an IT admin. |
actorId | The dashboard user id, the API key id, the IT admin’s email address, or the agent client’s client ID. |
action | A string such as "connection.saml_created" or "api_key.deleted". |
resourceType | For example "connection" or "api_key". |
resourceId | The id of the affected record, when one applies. |
details | Structured JSON context for the action. |
ipAddress | The client address of the request. For an agent entry, the address the sign-in service recorded. |
userAgent | The User-Agent header of the request. An agent entry has none. |
severity | "info" | "warn" | "error" | "critical". The default is "info". |
An agent entry records that an agent client signed in to its realm, or failed to. Its action is agent.authenticated or agent.authentication_failed. RealmSSO writes it from the sign-in service's events, up to a minute late. RealmSSO cannot see what the agent then does in your application. See Agent Identity API.
What is recorded
The server writes a row for changes made through the RealmSSO API. The table lists the action names at the time of writing. We read the names from the server code, not from a running instance. The list can change when the server changes.
| Area | Action names |
|---|---|
| Accounts | account.created, account.updated, account.domain_claimed, account.domain_verified, account.connection_error_policy_set, account.agent_access_enabled, account.agent_access_disabled |
| Connections | connection.saml_created, connection.oidc_created, connection.updated, connection.deleted, connection.tested, connection.idp_initiated_login, connection.idp_initiated_login_refused, connection.brokering_enforced, connection.brokering_divergence, connection.assertion_grant_enabled, connection.assertion_grant_disabled, connection.offline_access_enabled, connection.offline_access_disabled, connection.offline_access_divergence, connection.offline_access_unreadable |
| Sign-in client settings | sso_client.created, sso_client.updated, sso_client.secret_rotated, sso_mobile_client.created, sso_mobile_client.updated |
| Admin Portal | admin_portal.link_generated, admin_portal.saml_updated, admin_portal.oidc_updated, admin_portal.scim_updated |
| API keys | api_key.created, api_key.updated, api_key.deleted |
| Webhooks | webhook.created, webhook.updated, webhook.deleted, webhook.test_sent, webhook.delivery_redelivered |
| Agents | agent_client.registered, agent_client.revoked, connection.agent_principal_marked, agent_principal.revoked, agent.authenticated, agent.authentication_failed |
| Product grants | product_grant.created, product_grant.updated, product_grant.revoked, product_grant.provisioned, product_grant.deprovisioned, product_grant.handout_read, product_grant.secret_read, product_grant.secret_rotated |
A platform operator creates a product grant for an account. The product_grant.* rows record changes to the product grant. They also record each read of a handout or a secret.
What is not in the audit log
- Dashboard sign-ins. A dashboard user signs in with an email link, and RealmSSO writes no audit row for it.
- Sign-ins of your customers' users, SCIM syncs and Admin Portal sign-ins. These are events.
- Changes made directly in the sign-in service. Only changes made through RealmSSO are in the log.
Events carry an email address and an IP address. RealmSSO keeps events 90 days by default, then purges them. Events survive the deletion of an account until the purge. See Observability.
Best effort
RealmSSO writes each audit row in the background. If a write fails, the server logs the failure and the request still succeeds. An action can succeed with no audit row.
Who can read the audit log
Every member of the account can read its audit log. That includes the viewer role. An API key with the scope audit:read can read it too. Your customer's IT admin cannot read it.
The log has no export route and no streaming route. The API returns up to 200 rows for each page.
/api/v1/auditLists entries for one accountId. The query parameter accountId is required. You can filter by action, severity, actorType and since. Use page and limit to page through the rows.
/api/v1/audit/:idFetches one entry by id.
/api/v1/audit/summaryReturns counts by action and by severity for one account. The window is set by since. It defaults to the last 7 days.
GET /api/v1/audit?accountId=<account-id>&severity=warn&limit=50
X-API-Key: <your-api-key>How long rows last
Rows are deleted with the account
No job deletes audit rows. RealmSSO keeps them while the account exists. When you delete the account, its audit rows are deleted with it.
Two other records outlive an account. One is a deletion record. The other is a platform record of actions above any one account. Customers cannot read either record.