Skip to content
DashboardWebsite

Platform Admin

Just want to do it in the dashboard? See the guide: Find an organization and change its plan or Find a user and deactivate them or Lock an organization.

This page explains what platform administrators can do across organizations, how to manage users and settings, and how to run common operations. A platform administrator is a user with is_superadmin: true; this permission is separate from the per-org OrgRole ladder (viewer < member < admin < owner). OrgRole answers what a principal can do within one org. is_superadmin grants access to platform-wide operations. Being an owner of every org you belong to does not grant it.

A user can be an owner of three organizations and not be a platform administrator, or be a viewer in every org and be a platform administrator.


The GET /v1/admin/* and POST /v1/admin/* routes provide cross-tenant access:

EndpointDescription
GET /v1/admin/organizationsEvery organization on the instance — member count, spend, budget, and whether SSO is enabled
GET /v1/admin/organizations/{org_id}One organization’s summary, plus its full SSO connection parameters if configured (never the client secret — only whether one is set)
GET/PATCH/DELETE /v1/admin/organizations/{org_id}/members[/{user_id}], POST .../reset-password, POST .../reset-2faManage one org’s members without being a member of it — see Managing members below
GET /v1/admin/usersEvery user on the instance, with each organization they belong to and their role there — see Managing members below
PATCH /v1/admin/users/{user_id}, POST /v1/admin/users/{user_id}/reset-password, POST /v1/admin/users/{user_id}/2fa-resetEdit a user’s account-wide name or is_active, reset their password, or disable their two-factor authentication — see Managing members below
GET /v1/admin/usagePlatform-wide spend this month, broken down by org
GET /v1/admin/metrics/summaryPlatform-wide API request telemetry, broken down by org — see Auditing organizations below
GET /v1/admin/organizations/{org_id}/audit, GET /v1/admin/audit, GET /v1/admin/audit/exportStructured audit log — one org or a cross-org rollup — see Auditing organizations below
GET/POST /v1/admin/audit-sinks, GET/PATCH/DELETE /v1/admin/audit-sinks/{id}, POST …/{id}/test, POST /v1/admin/audit-sinks/drainPlatform audit sinks — see Audit Log Streaming
POST /v1/admin/users/{user_id}/superadminGrant or revoke another user’s is_superadmin flag
GET/POST /v1/admin/models, PATCH/DELETE /v1/admin/models/{llm_backend}/{model}Manage the platform-wide allowed-models catalog. This is not org-scoped data; these endpoints write shared state that every org’s /analyze and GitHub integration calls are checked against. The catalog is pre-populated with curated defaults at every startup. See the caution note at that link.
GET/PATCH /v1/admin/settingsThe admin-editable subset of the config file — see Settings below
POST /v1/admin/storage/prepare-mongodbReady a target MongoDB instance for use as the storage backend — see Preparing MongoDB below
GET /v1/admin/storageThe database this instance uses, plus the last MongoDB target prepared
GET /v1/admin/diagnosticsThe support bundle: a zip of versions, checks, the redacted configuration, recent warnings and the last failed jobs — see Logs and Troubleshooting
POST /v1/admin/retention/run, GET /v1/admin/retention/statusRun or check the last result of the retention sweep below
GET/POST /v1/admin/backups, GET/DELETE /v1/admin/backups/{id}, GET …/{id}/download, POST /v1/admin/backups/tickBackups of the whole database — see Backups and Restore
POST /v1/admin/jobs/sweep, GET /v1/admin/jobs/sweep-statusRun or check the last result of the stuck-job sweep below
DELETE /v1/admin/organizations/{org_id}, POST .../cancel-deletion, POST /v1/admin/organizations/purge-pendingSchedule, cancel, or hard-execute organization deletion below

A cross-org GET /v1/orgs/{org_id}/members call still returns 404 to a platform administrator who is not a member of that org, as it does for anyone else. To reach another org’s members, use the /admin/organizations/{org_id}/members route. The admin surface provides a narrow set of cross-tenant exceptions, such as member management and custom-rules management — see API Endpoints. It does not override org boundaries generally.

In the dashboard, the Platform Admin section appears in the sidebar only when GET /v1/auth/me reports is_superadmin: true. This is a user-interface check; each /admin/* page also checks access and shows an access-denied message if the user lacks the flag.

An organization’s detail page (Platform Admin → Organizations → (an org)) has five tabs: Overview (plan, spend, budget, lock state, 2FA policy), SSO, Members, Activity, and Danger zone (scheduled deletion). The open tab appears in the URL as ?tab= (…/admin/organizations/{org_id}?tab=members), so a link to a panel survives reloads and can be shared with another administrator. The page header shows org-wide states such as pending deletion, locked status, and plan tier.


A platform administrator can manage any org’s members from that org’s detail page, even without belonging to the org. They can change roles, toggle org-scoped active status, reset passwords or two-factor authentication, and remove members (Platform Admin → Organizations → an org → Members tab).

Platform Admin → Users lists every account on the instance (GET /v1/admin/users), including accounts that belong to no organization. Each row shows the user’s organizations and their role in each, account status, and sign-in method. The list shows 50 users per page, sorted by email. Type a filter and press Enter to match part of the name, email, or one of the user’s organization names. An organization badge opens that organization’s Members tab. The row’s Grant platform admin or Revoke platform admin button calls POST /v1/admin/users/{user_id}/superadmin.

The Users page has no other account actions. To edit an account, reset its password, or reset its two-factor authentication, open one of the user’s organizations from its badge and use the Members tab.

The endpoints split along the same line as the data model: Membership versus User.

  • /admin/organizations/{org_id}/members[/{user_id}] — org-scoped fields (role, is_active). These routes have the same guardrails as the org-admin-facing PATCH/DELETE /v1/orgs/{org_id}/members/{user_id}: role cannot be owner (transfer ownership directly instead), the action cannot target the caller’s own membership, and an org’s last remaining owner cannot be demoted, deactivated, or removed. Deactivating a member here blocks only their access to this org. Their other org memberships and account remain unchanged.
  • /admin/users/{user_id} — account-wide fields (name, is_active) and account-wide password reset. Deactivating a user here blocks login everywhere and ends every session they hold. The dashboard presents these actions separately from the per-membership actions on the Members card.

Both password-reset endpoints (org-scoped and account-wide) clear the password, sign the account out everywhere, and email a single-use link to choose a new password. The link is also returned once for handover when the deployment uses the log mail backend and sends no email.

Both password resets end every session held by the target, as do the two-factor reset and POST /v1/admin/users/{user_id}/superadmin. Session cookies are stateless JWTs, but each request checks the account behind the cookie. If an account has been deactivated or its sessions revoked, the next request returns 401 instead of waiting for session.access_ttl_minutes to expire. This also applies to the is_superadmin flag: the claim is baked into the token when it is created, but revoking the flag revokes the target’s sessions. A demoted platform administrator loses /admin/* access immediately. See Session lifetime and revocation for what revokes sessions.

Password-reset endpoints return 400 for SSO-backed accounts (auth_provider != "local"), because those accounts have no local password to reset.


In the dashboard, settings are grouped under Platform Admin → Security (Rate Limits, Sign-in Providers, Sign-up & Sessions, Agents), Connections (GitHub Webhooks, Audit Streaming, and the product’s GitLab, Jira and LLM Endpoints), and System (General, Data Lifecycle, Jobs, Storage). The product adds an Analysis category with Engine, Agent Injection, and Review Feedback.

The logging, registration, branding, social_login, server, session, rate_limit thresholds (but not enabled), retention, jobs, org_offboarding, agent_access, and any sections registered by a mounted product are not read from the config file or environment. They use hardcoded defaults unless an administrator sets overrides through GET/PATCH /v1/admin/settings. GET /v1/admin/settings returns each field’s effective value, which fields are overridden, and which sections are excluded and why. Some excluded sections are file/env-driven; others have no override mechanism. PATCH /v1/admin/settings takes a partial body: it changes only fields you include. Setting a field to null clears its override and restores the hardcoded default.

If the config file sets one of these fields, the server ignores the value. At boot, it logs a warning. GET /v1/admin/settings lists the field and file value under ignored_file_settings, and the dashboard shows a note under the field.

Terminal window
curl -X PATCH http://localhost:8000/v1/admin/settings \
-H "X-API-Key: <admin-key>" \
-H "Content-Type: application/json" \
-d '{"server_max_input_size_mb": 25, "logging_level": "debug"}'

One field to note is registration_allow_public_org_creation. Set it to false to stop users from creating a new organization with POST /v1/auth/register and org_name, or POST /v1/orgs. This makes new org creation invite-only without changing who can register an account.

Terminal window
curl -X PATCH http://localhost:8000/v1/admin/settings \
-H "X-API-Key: <admin-key>" \
-H "Content-Type: application/json" \
-d '{"registration_allow_public_org_creation": false}'

A platform administrator is exempt from this setting, so POST /v1/orgs still works for them. See Configuration Reference — registration for what the setting affects. Org-less registration and invite acceptance are unaffected because neither creates a new org.

The dashboard follows the setting: when it is off, the sign-up page removes the option to create an organization and its org-name field. The onboarding page for an org-less account shows a note to use an invite link or ask an administrator instead of the create-organization form. Both pages read GET /v1/auth/registration-options, a public endpoint that mirrors this setting. They pick up changes on the next page load without a restart or re-login. These controls affect presentation; the two endpoints above enforce the setting.

Platform Admin → Security → Sign-in Providers (a General tab plus one tab per provider) holds social_login_*: the platform-wide Continue with Google / Microsoft buttons, their OAuth client IDs and write-only client secrets, and the master switch social_login_enabled, which hides every button without discarding stored credentials. See Quick Start: Sign in with Google or Microsoft for app registration and how provider sign-in interacts with an org’s SSO connection.

logging.level, registration.*, branding.*, social_login.*, and every server.* field apply to the next request without a restart. session.access_ttl_minutes applies to the next login, registration, or session switch; it does not extend a session cookie a user already holds. retention.* fields are also read fresh per request. retention_telemetry_days and retention_audit_days additionally update the running MongoDB TTL indexes through collMod — see Data Retention and Running a retention sweep manually below. org_offboarding_grace_period_days is read fresh per request — see Deleting an organization below.

The five rate_limit_* thresholds (Platform Admin → Security → Rate Limits) apply to the next request. They set failed-login attempts per account, second-factor attempts per account, and failed credentials per source IP across credential types. rate_limit.enabled is not available through this endpoint: a PATCH that names it returns 422, and GET does not return it. Whether rate limiting runs remains a config-file decision. This setting covers application-level attempt limits; request-rate limiting by source IP belongs at the deployment’s ingress. See Configuration Reference — rate_limit. storage, cors, auth, jwt, two_factor, and secrets are not part of this endpoint; they are file/env-driven for reasons described in Configuration Reference — Platform settings. telemetry is also excluded, but for a different reason: the server reads it once, synchronously, inside create_app() before the FastAPI app exists to make an asynchronous database read. No restart-free admin API change can update it. Its value stays at the hardcoded default for the process lifetime. Here, telemetry means only its enabled flag; the retention duration for its spans is configured separately under retention.

In the dashboard: Platform Admin → Security → Agents.

The agent_access section governs access tokens, which agents and scripts use to act as a person, and the MCP service. The server reads every field on each request:

FieldDefaultEffect
agent_access_tokens_enabledtruefalse refuses every access token (401) and blocks creating new ones. API keys are not affected
agent_access_max_token_days90The longest lifetime a new token may have, 1 to 365 days
agent_access_default_token_scopereadThe scope a new token gets when its creator names none
agent_access_platform_mcp_enabledtruefalse refuses (403) every call the platform MCP service makes for an agent

An org admin can set a stricter policy in their org (Agent access), but not a looser one.

In the dashboard: Platform Admin → Security → Firewall. This page shows which source addresses may reach the API, dashboard, and docs. See Network Access for how rules decide access.

  • Overview shows each filter in request order: trusted proxies, network rules per service (longest prefix first, with the built-in /health allow and the default “allow” row), and each API key’s allowlist. Warnings appear on rows for a failed list refresh, a rule on a service not wired to the API, or a key no address can use. Trace a request takes a service, address, path, and optional key, then shows where the request stops.
  • Rules — create, edit, and delete rules. New rules start in report mode.
  • IP lists — address lists, with their source, entry count, last refresh, and errors.
  • Traffic — refused requests, newest first, and the most-refused addresses.

If “Your address” in the header shows a container address, check network.trusted_proxies and correct it before writing a rule.

In the dashboard: Platform Admin → System → Migrations.

A release that changes how documents are stored ships a migration. The server applies pending migrations at startup, before it serves requests. GET /v1/admin/migrations lists migrations applied to this database, newest first, with the number of documents each changed. pending is empty on a running server.

  • One replica runs migrations. The others wait.
  • With backups enabled, the server takes a backup first. If the backup fails, no migration is applied and the server stops.
  • A server whose image is older than the database’s last migration refuses to start. See Upgrade and roll back.

In the dashboard: Platform Admin → System → Database.

POST /v1/admin/storage/prepare-mongodb is the API and dashboard equivalent of opentremor-admin init-db. Given a target uri and database (which need not be the database this instance runs on), it idempotently creates every collection and index the app relies on, and can optionally create a dedicated app user.

Terminal window
curl -X POST http://localhost:8000/v1/admin/storage/prepare-mongodb \
-H "X-API-Key: <admin-key>" \
-H "Content-Type: application/json" \
-d '{
"uri": "mongodb://localhost:27017",
"database": "opentremor",
"app_username": "opentremor_app",
"app_password": "changeme"
}'

This does not change which database the running instance uses. That database is set by storage.mongodb in the config file, read at startup. If the uri lacks privileges to create users on its server, provide admin_uri for the app-user-creation step.

GET /v1/admin/storage returns the database this instance uses and the uri and database last used with prepare-mongodb. It does not return admin_uri, app_username, or app_password; those are one-time bootstrap secrets and are not stored. The dashboard’s Platform Admin → System → Database page uses the returned values to prefill the form.


In the dashboard: Platform Admin → System → Data Lifecycle → Run sweep now.

See Data Retention for the full policy. This section covers the two admin actions. POST /v1/admin/retention/run purges resolved (acknowledged, suppressed, or false-positive) findings past their configured severity-tiered window and redacts raw resource content past its own window, then records the outcome. The endpoint is self-gating: if called again before retention.sweep_interval_hours has elapsed, it returns the previous result with skipped: true instead of repeating the work. This lets OpenTremor-task-scheduler call it every few minutes without knowing the configured interval. Pass force=true to bypass the gate and run immediately. The dashboard’s Platform Admin → System → Data Lifecycle → Run sweep now button does this.

Terminal window
# Routine heartbeat call — a no-op most of the time
curl -X POST http://localhost:8000/v1/admin/retention/run -H "X-API-Key: <admin-key>"
# Force an immediate run regardless of the configured interval
curl -X POST "http://localhost:8000/v1/admin/retention/run?force=true" -H "X-API-Key: <admin-key>"

GET /v1/admin/retention/status returns the last real run’s result (null if a sweep has never run on this instance): duration_ms, error if the last run failed partway through, and counts, a map of how many records each sweep step touched. For example: {"findings_purged": 3, "resources_redacted": 1}. The keys can vary; see the endpoint reference.


Background jobs run from a queue. Each replica’s worker claims jobs under a lease. When a worker dies, a job returns to the queue after its lease expires (see Background jobs). Workers handle this as they poll; the sweep also handles it when no worker is running. POST /v1/admin/jobs/sweep re-queues each running job whose lease expired, or marks it failed once it has been claimed jobs.max_attempts times. It also marks as failed each running job, and each in-process job still queued, with no progress update in over jobs.stuck_timeout_minutes (default 60), across all orgs. Like the retention sweep, it is self-gating: if called again before jobs.sweep_interval_hours has elapsed, it returns the previous result with skipped: true instead of repeating the work. Pass force=true to bypass the gate. The dashboard’s Platform Admin → System → Jobs → Jobs sweep → Run sweep now button does this.

Terminal window
# Routine heartbeat call — a no-op most of the time
curl -X POST http://localhost:8000/v1/admin/jobs/sweep -H "X-API-Key: <admin-key>"
# Force an immediate run regardless of the configured interval
curl -X POST "http://localhost:8000/v1/admin/jobs/sweep?force=true" -H "X-API-Key: <admin-key>"

GET /v1/admin/jobs/sweep-status returns the last real run’s result (null if a sweep has never run on this instance): jobs_marked_failed, jobs_requeued, duration_ms, and error if the last run failed partway through. You can resume a job marked failed by the sweep — see Retrying a failed job below.


In the dashboard: Platform Admin → Organizations → (an org), Danger zone tab.

Deletion is scheduled, not immediate. DELETE /v1/admin/organizations/{org_id} sets locked: true (org-scoped endpoints return 423 right away) and pending_deletion_at: now. It does not remove data yet. The org is hard-deleted, including its org-scoped collections (resources, findings, custom rules, teams, API keys, and more — see Configuration Reference — org_offboarding), after pending_deletion_at is more than org_offboarding.grace_period_days (default 30) in the past and POST /v1/admin/organizations/purge-pending runs.

Terminal window
# Schedule — locks the org immediately, does not delete anything yet
curl -X DELETE http://localhost:8000/v1/admin/organizations/{org_id} -H "X-API-Key: <admin-key>"
# Cancel any time before the grace period elapses
curl -X POST http://localhost:8000/v1/admin/organizations/{org_id}/cancel-deletion -H "X-API-Key: <admin-key>"

Cancelling clears pending_deletion_at but does not unlock the org. Unlocking remains a separate PATCH .../lock call because the org may have been locked for another reason. Both operations return 409 if the org is already in the state you are asking to change it out of: scheduling deletion for an org already pending deletion, or cancelling deletion for an org not pending deletion.

POST /v1/admin/organizations/purge-pending performs the irreversible deletion. It is normally called by OpenTremor-task-scheduler’s heartbeat. Like the retention sweep, core has no scheduler of its own. The endpoint is a no-op when no deletion is due, so it can be called as often as needed.

Terminal window
curl -X POST http://localhost:8000/v1/admin/organizations/purge-pending -H "X-API-Key: <admin-key>"
{
"purged": [{"org_id": "...", "name": "..."}],
"errors": []
}

If one org’s purge fails, the batch continues with other due orgs. The failed org’s ID and error message appear in errors.


In the dashboard: Analysis → Jobs, then expand the job and choose Retry.

Any org member can retry a job in their org; this is the same permission required to launch one. This section covers retry because it is a companion to the stuck-job sweep above. POST /v1/jobs/{job_id}/retry resumes a job that failed in the middle of processing — see API Reference — POST /jobs/{job_id}/retry for the full contract. It creates a new job_id (retry_of links to the original, which remains unchanged) and processes only changeset items the original job has not already analyzed. The dashboard’s Jobs page shows Retry for eligible failed jobs.

Terminal window
curl -X POST http://localhost:8000/v1/jobs/{job_id}/retry -H "X-API-Key: <org-key>"

Org admins have GET /v1/metrics/{summary,spans,usage} scoped to their own org (see API Endpoints → Metrics) and a structured audit log of privileged actions, such as settings changes, key creation or revocation, plan and lock changes, superadmin grants, SSO changes, and finding triage. That log is also scoped to their org. A platform administrator can access the following across orgs:

  • GET /v1/admin/metrics/summary — the API-request rollup, broken down by by_org, across all organizations. A mounted product may add a cross-org rollup of its own data; the analysis engine’s route is GET /v1/admin/analysis/metrics/summary.
  • GET /v1/admin/organizations/{org_id}/audit — one org’s audit log, even when the administrator is not a member of that org.
  • GET /v1/admin/audit — the cross-org audit feed. Omit org_id for a rollup across all orgs, including org-less platform actions such as a superadmin grant that affects a user, not an org. Pass org_id to filter to one org.
  • GET /v1/admin/audit/export — download the cross-org or one-org feed as CSV or JSON, up to 10,000 rows.
  • /admin/audit-sinks — platform sinks that stream every event to a SIEM over HTTPS or syslog. See Audit Log Streaming.

In the dashboard, this is Platform Admin → Security → Audit Log — an org picker (default All organizations) and the filter and export controls used on the org-scoped Audit Log page. An organization’s detail page (Platform Admin → Organizations → (an org) → Activity) also shows its five most recent audit events, with a link to the full filtered view.


  • The bootstrap key (config.auth.api_key) and auth-disabled mode (api_key: null) both resolve as superadmin automatically. Both are already root-equivalent: the bootstrap key owns the default org without further checks.
  • Human accounts carry users.is_superadmin: bool (default false). The flag is included in the session JWT at login or session-switch time, like org_id and role. Granting or revoking the flag ends the target’s sessions. The target must sign in again to receive the updated flag.
  • API keys do not carry the flag. A stored key has no backing user from which to read it.

POST /v1/admin/users/{user_id}/superadmin requires an existing superadmin, so there is no in-app way to create the first one. You can bootstrap one of two ways.

Set auth.default_admin_email and auth.default_admin_password in your config, or set the DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD environment variables — see Configuration Reference. The account is created once, idempotently, the first time the server starts with these values set. For Docker Compose or quickstart, rotate the shipped defaults ([email protected] / local-dev-password) before using the deployment in production.

Terminal window
opentremor-admin grant-superadmin --email [email protected]
# in the container image:
docker compose exec opentremor-core python -m opentremor_core.cli grant-superadmin --email [email protected]

The target user must already exist; register the account with POST /v1/auth/register first. See opentremor-admin grant-superadmin for the full option list.