Administration

Credential model

Administrator access tokens default to a short lifetime (15 minutes in the standard configuration), while refresh tokens default to 30 days and rotate on use. A rotated refresh token stays valid for a 60-second reuse window so concurrent refreshes from parallel requests or multiple tabs do not end the session. Disabled users are checked against database state on authenticated requests.

Platform and tenant roles

Viewer and read-key compute-only POST routes include monitor test, import preview, dependency suggestions, mesh probe, and AI connection test. Persisted operations such as Run now, channel test, acknowledgement, or configuration updates require write authorization.

Bootstrap and manage users

On an empty installation, the public bootstrap status and first-user endpoints allow exactly the initial account to be created. That first active account is a superadministrator. OIDC just-in-time login can also initialize the first superadministrator on an empty installation.

A user with email and no password can be provisioned as SSO-only. Superadministrator-only user routes create, list, update, and delete accounts. Safeguards prevent deleting the current user or leaving the installation without an administrator.

Tenant context

An administrator session can select a tenant using X-Tenant-ID; a tenant_id query fallback is supported by the authentication context where applicable. The server verifies membership unless the user is a superadministrator.

API keys ignore arbitrary tenant selection and remain pinned to their creation tenant. The tenant-list endpoint is for administrator sessions and returns only allowed tenant context. Public tenant create/update/delete management is not exposed through the normal product API.

API keys

curl -H 'Authorization: Bearer pk_<secret>' \
  https://monitoring.example.com/api/v1/monitors

1. Create the key as a tenant administrator and choose the minimum scope.
2. Copy the full key from the one-time creation response into a secret manager.
3. Use key_prefix to identify the key record later; it is a derived identifier, not a recognizable fragment of the secret, and list responses never reveal the full key.
4. Set an expiration and rotate before it, rather than keeping indefinite integration credentials.
5. Revoke the key when a client is retired or the secret may have leaked.

last_used_at is intentionally not updated on every request; writes are throttled to roughly five-minute granularity. Use it for coarse inventory, not per-request forensics.

OpenID Connect

Probara supports one platform identity provider using the authorization-code flow with PKCE. Signed state cookies and nonce validation protect the browser redirect. Provider discovery is loaded lazily as the login flow needs it.

• OIDC identities are bound by the stable (issuer, subject) pair.
• A verified email can link to an explicitly SSO-only account.
• An unverified email is not trusted for account linking.
• A subject already bound to another account is refused.
• When just-in-time provisioning is enabled, new users receive the configured default platform/tenant membership rather than arbitrary claims-based privilege — unless OIDC group mappings exist, in which case mapped roles replace the JIT defaults.
• On an empty installation, the first successful JIT login becomes the initial superadministrator.

OIDC group mappings

Superadmins can map identity-provider groups to roles under Settings → OIDC group mappings (or via /api/v1/oidc-group-mappings). A mapping targets either one tenant with a role (admin, editor, viewer) or the platform (grants superadmin). Groups are read from the ID-token claim named by `OIDC_GROUPS_CLAIM`; request the groups scope via OIDC_SCOPES so the provider sends it.

• Zero mappings means the feature is off: JIT defaults apply and roles stay manually managed. Deleting all mappings restores that behavior immediately.
• With any mappings present, the identity provider is the source of truth for SSO users: platform role and tenant memberships are re-derived from the user's groups on every login, overwriting manual edits.
• A user in several groups mapping to the same tenant gets the highest role (admin > editor > viewer). Group names match case-sensitively.
• A user in no mapped groups syncs to a member with no tenant memberships — deliberately no fallback to the JIT default, which would silently re-grant revoked access.
• The sync never demotes the last active superadmin; the demotion is skipped and flagged in the audit log (skipped_last_superadmin_demotion).
• Password-based accounts are never touched by group sync.
• Applied changes are recorded as auth.oidc_role_sync audit events with the full membership diff, the matched groups, and every group the token presented (received_groups) — the place to look when a name doesn't match.
• Groups presented in verified ID tokens at successful logins are catalogued and offered as suggestions in the mapping editor (with click-to-prefill chips for groups that have no mapping yet). OIDC has no API to enumerate an IdP's groups, so the catalog only knows groups someone has already logged in with.
• Mappings accept an optional display label (click a row's group cell to edit). Matching always uses the raw claim value — essential with Azure AD, whose groups claim carries object IDs (GUIDs), not names: label the GUID rows so the table stays readable.

Tenant settings

Retention applies to monitoring telemetry such as check results, mesh history, and rollups. Audit retention is configured separately at platform level. Dashboard group tags change presentation only; they do not create monitor groups or notification rollup.

Tenant AI settings

Tenant settings override effective environment fallback configuration when present. The API key is encrypted at rest when the platform master encryption key is configured. The connection-test action is compute-only and can be run without saving a new monitor or incident.

AI configuration enables dependency suggestions and asynchronous incident analysis. It does not automatically apply suggested graph edges or remediation steps.

Audit log

Tenant administrators and platform superadministrators can review audit events for mutations and important authentication/authorization paths. Records include actor type, identifier and label, action, resource, outcome, HTTP status, IP address, user agent, structured details, and timestamp.

Audit writes are best-effort asynchronous operational records, not a transactional ledger. The platform AUDIT_RETENTION_DAYS setting defaults to 365 days; 0 keeps records indefinitely.

Import monitors

Monitor imports support JSON, YAML, and CSV with format autodetection. JSON/YAML can contain an array, a single object, common wrappers such as items, monitors, or data, a versioned portable YAML bundle, and an Uptime Kuma backup export. YAML also recognizes common source wrappers such as services, endpoints, and checks.

Two source schemas are recognized and translated automatically, so the field-mapping step is already complete when preview reports them: the portable bundle (portable_monitor_export) and an Uptime Kuma export (uptime_kuma_export). Everything else goes through field mapping.

1. Upload the source to import preview.
2. Review detected field/type mappings, normalization, warnings, and row errors.
3. Correct ambiguous group members and unsupported types.
4. Execute the import and retain the per-row created/skipped/error report.
5. Open created monitors and test credentials, location assignments, notification routing, and dependencies before enabling broad alerting.

Mapped/simple import currently specializes in HTTP, ping, DNS, gRPC, and groups. Defaults include a 60-second interval, 30-second timeout, and enabled state when omitted. Duplicate name+type combinations are matched case-insensitively and skipped.

Migrating from Uptime Kuma

Upload an Uptime Kuma backup export and the importer translates monitor types, assertions, tags, retry tolerance, and group nesting on its own. Uptime Kuma 1.x writes that file from Settings → Backup → Export. Version 2.0 removed the backup button and Uptime Kuma has never had a REST API, so scripts/kuma-export in this repository logs into a running instance over its socket.io API and writes the same file: go run ./scripts/kuma-export -url https://kuma.internal -user admin (password from -pass or $KUMA_PASSWORD, plus -totp when two-factor is enabled).

Translated types: http, keyword (a body assertion, inverted for invert-keyword), and json-query (a JSON path assertion) become HTTP monitors; port becomes TCP; ping and dns map directly; push becomes a push monitor; grpc-keyword becomes a gRPC health probe; postgres, mysql, mongodb, and redis map to their database monitors; and group becomes a group, with Uptime Kuma's parent links inverted into membership so nesting survives.

Accepted status codes become explicit status ranges, redirect limits and TLS verification carry over on HTTPS monitors, and Uptime Kuma's certificate-expiry notification becomes tls_min_days_valid, which raises a dedicated TLS-expiry alert rather than failing the check — the same notify-only behavior. Retry counts land in consecutive_failures_threshold, clamped to 1-10.

Monitors with no faithful equivalent are listed as not imported rather than approximated: docker, sqlserver, steam, gamedig, mqtt, kafka-producer, radius, snmp, tailscale-ping, manual, smtp, real-browser, and rabbitmq — Uptime Kuma polls the RabbitMQ management HTTP API while this platform performs an AMQP handshake, so recreate those by hand. Unsupported DNS record types and port monitors without a port are reported the same way.

Export monitors

The monitor export endpoint produces a versioned YAML bundle with monitor configuration, tags, retry thresholds, and group membership names. Compatibility data can include legacy alert-policy names, but policy management is retired. Export only produces this portable bundle — there is no Uptime Kuma-direction export.

Administration checklist

• Keep at least two controlled superadministrator recovery paths.
• Grant tenant editor or viewer by default and reserve admin for governance tasks.
• Issue integration-specific, expiring API keys with the minimum scope.
• Test OIDC login and local/recovery login after every proxy, issuer, or public-origin change.
• Review audit events, inactive users, stale API keys, and tenant memberships on a schedule.
• Define both telemetry and audit retention intentionally.
• Treat AI output as advisory and protect provider API keys with platform secret encryption.
• Always preview monitor imports and test imported monitors before relying on them for production alerts.