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.
What it grants
Section titled “What it grants”The GET /v1/admin/* and POST /v1/admin/* routes provide cross-tenant access:
| Endpoint | Description |
|---|---|
GET /v1/admin/organizations | Every 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-2fa | Manage one org’s members without being a member of it — see Managing members below |
GET /v1/admin/users | Every 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-reset | Edit 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/usage | Platform-wide spend this month, broken down by org |
GET /v1/admin/metrics/summary | Platform-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/export | Structured 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/drain | Platform audit sinks — see Audit Log Streaming |
POST /v1/admin/users/{user_id}/superadmin | Grant 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/settings | The admin-editable subset of the config file — see Settings below |
POST /v1/admin/storage/prepare-mongodb | Ready a target MongoDB instance for use as the storage backend — see Preparing MongoDB below |
GET /v1/admin/storage | The database this instance uses, plus the last MongoDB target prepared |
GET /v1/admin/diagnostics | The 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/status | Run 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/tick | Backups of the whole database — see Backups and Restore |
POST /v1/admin/jobs/sweep, GET /v1/admin/jobs/sweep-status | Run 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-pending | Schedule, 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.
Managing members
Section titled “Managing members”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-facingPATCH/DELETE /v1/orgs/{org_id}/members/{user_id}:rolecannot beowner(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.
Settings
Section titled “Settings”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.
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.
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.
Agent access
Section titled “Agent access”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:
| Field | Default | Effect |
|---|---|---|
agent_access_tokens_enabled | true | false refuses every access token (401) and blocks creating new ones. API keys are not affected |
agent_access_max_token_days | 90 | The longest lifetime a new token may have, 1 to 365 days |
agent_access_default_token_scope | read | The scope a new token gets when its creator names none |
agent_access_platform_mcp_enabled | true | false 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.
Firewall
Section titled “Firewall”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
/healthallow 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.
Schema migrations
Section titled “Schema migrations”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.
Preparing MongoDB
Section titled “Preparing MongoDB”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.
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.
Running a retention sweep manually
Section titled “Running a retention sweep manually”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.
# Routine heartbeat call — a no-op most of the timecurl -X POST http://localhost:8000/v1/admin/retention/run -H "X-API-Key: <admin-key>"
# Force an immediate run regardless of the configured intervalcurl -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.
Running a stuck-job sweep manually
Section titled “Running a stuck-job sweep manually”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.
# Routine heartbeat call — a no-op most of the timecurl -X POST http://localhost:8000/v1/admin/jobs/sweep -H "X-API-Key: <admin-key>"
# Force an immediate run regardless of the configured intervalcurl -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.
Deleting an organization
Section titled “Deleting an organization”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.
# Schedule — locks the org immediately, does not delete anything yetcurl -X DELETE http://localhost:8000/v1/admin/organizations/{org_id} -H "X-API-Key: <admin-key>"
# Cancel any time before the grace period elapsescurl -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.
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.
Retrying a failed job
Section titled “Retrying a failed job”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.
curl -X POST http://localhost:8000/v1/jobs/{job_id}/retry -H "X-API-Key: <org-key>"Auditing organizations
Section titled “Auditing organizations”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 byby_org, across all organizations. A mounted product may add a cross-org rollup of its own data; the analysis engine’s route isGET /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. Omitorg_idfor a rollup across all orgs, including org-less platform actions such as a superadmin grant that affects a user, not an org. Passorg_idto 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.
Who has it
Section titled “Who has it”- 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 thedefaultorg without further checks. - Human accounts carry
users.is_superadmin: bool(defaultfalse). The flag is included in the session JWT at login or session-switch time, likeorg_idandrole. 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.
Bootstrapping the first superadmin
Section titled “Bootstrapping the first superadmin”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.
Declaratively, at startup
Section titled “Declaratively, at startup”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.
Against a running database
Section titled “Against a running database”# 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.