Permissions (RBAC)
Every API route belongs to exactly one action - a resource:verb key such as flow:view or run:trigger - declared in apps/api/auth/actions.yaml with a default policy and a description. apps/api/auth/routes.yaml maps every route to its action, and the loader in apps/api/auth/permissions.py flattens the two files into the rule table that RBACMiddleware enforces on every request (most specific path wins). A route's default policy is its action's policy. This page lists the 123 actions across 47 resources, in registry order, with the 395 route rules they cover.
Administrators change who may do what at runtime under Settings → Permissions, which has two tabs:
- Actions allocates a whole action to a policy; every route of the action follows (stored in
permission_action_overrides). - Routes pins a single method and path to a policy as an escape hatch; a route override wins over its action (stored in
permission_overrides).
The policy in effect for a request is resolved as route override → action override → action default. Structural policies cannot be overridden at either layer, the pinned permission:manage keeps its default policy so no override can hand the permission matrix to a lower role, and a target-org policy can only be assigned where every affected route carries an {org_ref} parameter. One override target is not a role: disabled switches the action or route off for every caller until an administrator assigns another policy. No action may declare it as its default, and auth:me refuses it at both layers so the console can always load and reach this editor to undo it. Overrides are audited, applied immediately on the API instance that saved them and within 30 s on every other instance, and surfaced by the same endpoints that power that page (GET /settings/permissions/actions and GET /settings/permissions). Both override layers round-trip through configuration exchange as the permission_action_overrides and permission_overrides bundle sections. The OpenAPI schema carries the effective security requirement per operation.
Some routes also need step-up authentication: a caller the policy admits must have signed in within HEGEMONY_STEP_UP_MAX_AGE_SECONDS, and personal access tokens and service accounts are refused. They are marked under their action below (the step_up field in apps/api/auth/actions.yaml). The marks are the default: an administrator switches step-up authentication per action in the Fresh sign-in column of the Actions tab (stored in permission_step_up_overrides), except for the pinned permission:manage. The column shows on how many of an action's routes it asks; the action's route list marks which ones. See Step-up authentication.
Policies
| Policy | Who it grants | Overridable |
|---|---|---|
public | No authentication required | no (structural) |
authenticated | Any authenticated caller | yes |
viewer | Granted to roles admin, auditor, editor, operator, viewer | yes |
auditor | Granted to roles admin, auditor, editor, operator | yes |
operator | Granted to roles admin, editor, operator | yes |
editor | Granted to roles admin, editor | yes |
approver | Granted to roles admin, approver | yes |
admin | Granted to roles admin | yes |
org_member | Authorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs any membership in that organization | yes |
org_admin | Authorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs the admin membership role in that organization | yes |
internal | Worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true) | no (structural) |
custom | The endpoint authenticates the caller itself | no (structural) |
disabled | Nobody — the endpoint is switched off for every caller, platform admins included, until an administrator assigns another policy | yes |
system
system:health
Liveness and readiness probes.
Default policy: public — no authentication required.
| Methods | Path |
|---|---|
| GET | /health |
| GET | /ready |
system:docs
Interactive API documentation and the OpenAPI schema.
Default policy: public — no authentication required.
| Methods | Path |
|---|---|
| GET | /docs/oauth2-redirect |
| GET | /openapi.public.json |
| GET | /openapi.json |
| GET | /redoc |
| GET | /docs |
system:version
The Hegemony release this instance runs, with the commit and date of its build. Signed-in callers only: the version tells an outsider which known vulnerabilities apply.
Default policy: authenticated — any authenticated caller.
| Methods | Path |
|---|---|
| GET | /system/version |
auth
auth:config
OIDC discovery for the UI and BFF ticket validation.
Default policy: public — no authentication required.
| Methods | Path |
|---|---|
| GET | /auth/bff/validate |
| GET | /auth/config |
auth:me
The caller's own identity, effective roles, capabilities and BFF tickets.
Default policy: authenticated — any authenticated caller. Reallocatable but never disableable: the console loads it before it can render anything, so switching it off would leave no way back to the permission editor.
| Methods | Path |
|---|---|
| GET | /auth/capabilities |
| POST | /auth/bff/ticket |
| GET | /auth/me |
org
org:list
List organizations (filtered per caller in the router).
Default policy: authenticated — any authenticated caller.
| Methods | Path |
|---|---|
| GET | /orgs |
org:view
Read an organization and its member list.
Default policy: org_member — authorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs any membership in that organization.
| Methods | Path |
|---|---|
| GET | /orgs/{org_ref}/members |
| GET | /orgs/{org_ref} |
org:manage
Create, rename, deactivate and delete organizations (platform admin), and designate the shared organization whose resources become readable by every tenant.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE, PATCH | /orgs/{org_ref} |
| POST | /orgs |
org_member
org_member:manage
Add, change the role of, and remove organization members.
Default policy: org_admin — authorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs the admin membership role in that organization. The routes marked below need a fresh sign-in (step-up authentication).
| Methods | Path | Fresh sign-in |
|---|---|---|
| GET | /orgs/{org_ref}/addable-users | |
| POST | /orgs/{org_ref}/members | yes |
| DELETE, PATCH | /orgs/{org_ref}/members/{user_id} | yes |
org_idp_mapping
org_idp_mapping:manage
Maintain IdP group-claim to organization-role mappings; these grant org roles, including org admin, automatically at login.
Default policy: org_admin — authorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs the admin membership role in that organization.
| Methods | Path |
|---|---|
| GET, POST | /orgs/{org_ref}/idp-mappings |
| DELETE, PATCH | /orgs/{org_ref}/idp-mappings/{mapping_id} |
internal
internal:run_callbacks
Worker run-execution callbacks: create child runs, read run state and outputs, replace run vars, report step, event, artifact and approval progress, cancel runs and assign shared workers.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| POST | /internal/step-runs/{step_run_id}/window-wait/settle |
| POST | /internal/runs/{run_id}/ssh-host-keys/mismatch |
| POST | /internal/runs/{run_id}/tf-state-hold/release |
| POST | /internal/runs/{run_id}/assign-shared-worker |
| POST | /internal/runs/{run_id}/ssh-host-keys/trust |
| POST | /internal/runs/{run_id}/ssh-host-keys/learn |
| POST | /internal/runs/{run_id}/artifacts/upload |
| POST | /internal/runs/{run_id}/tf-state-access |
| POST | /internal/runs/{run_id}/secrets/delete |
| POST | /internal/runs/{run_id}/inventory/sync |
| POST | /internal/runs/{run_id}/secrets/write |
| POST | /internal/runs/{run_id}/secrets/read |
| GET | /internal/runs/{run_id}/step-outputs |
| POST | /internal/runs/{run_id}/step-access |
| POST | /internal/runs/{run_id}/file-links |
| POST | /internal/runs/{run_id}/artifacts |
| POST | /internal/runs/{run_id}/approvals |
| POST | /internal/runs/{run_id}/step-runs |
| PUT | /internal/runs/{run_id}/run-vars |
| GET | /internal/runs/{run_id}/outputs |
| POST | /internal/runs/{run_id}/cancel |
| POST | /internal/runs/{run_id}/events |
| POST | /internal/runs |
| DELETE | /internal/runs/{run_id}/tf-state-access/{token_id} |
| DELETE | /internal/runs/{run_id}/step-access/{provider} |
| DELETE | /internal/runs/{run_id}/file-links/{token_id} |
| PATCH | /internal/step-runs/{step_run_id} |
| PATCH | /internal/approvals/{approval_id} |
| GET, PATCH | /internal/runs/{run_id} |
internal:monitor_callbacks
Worker monitor callbacks: create and update monitors, poll for an external stop, batch-insert samples and finalize a run's monitors.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| POST | /api/v1/monitor-samples/batch |
| POST | /api/v1/monitors |
| POST | /api/v1/monitors/set-status-for-run/{run_id} |
| POST | /api/v1/monitors/finalize-for-run/{run_id} |
| GET | /api/v1/monitors/{monitor_db_id} |
| PATCH | /api/v1/monitors/{monitor_db_id} |
internal:resolve
Worker lookups of attachments, subscriptions, destinations, backends and variables.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| GET | /internal/flows/{flow_id}/notification-subscriptions |
| GET | /internal/runs/{run_id}/registry-credentials |
| GET | /internal/flows/{flow_id}/attachments |
| GET | /internal/runs/{run_id}/attachments |
| GET | /internal/runs/{run_id}/trusted-cas |
| GET | /internal/secrets-backends |
| GET | /internal/variables |
| GET | /internal/notification-destinations/{destination_id} |
internal:scheduler
Scheduler callbacks for due schedules and maintenance ticks.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| POST | /internal/schedules/{schedule_id}/trigger |
| POST | /internal/maintenance/tick |
| GET | /internal/schedules/due |
internal:platform_configuration
Workers and the scheduler read the platform settings stored in the UI, to apply them. Never includes a secret.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| GET | /internal/platform-configuration/overrides |
internal:worker_registry
Worker heartbeats (the Workers registry) and each worker's report of the environment-variable names it exposes.
Default policy: internal — worker and scheduler callbacks presenting X-Internal-Token (not checked when auth is disabled, or when no token is configured and HEGEMONY_INTERNAL_API_TOKEN_OPTIONAL=true).
| Methods | Path |
|---|---|
| POST | /internal/workers/heartbeat |
| POST | /internal/runtime/env-keys |
| DELETE | /internal/runtime/env-keys/{worker_id} |
run
run:stream
Live run event and monitor streams over SSE.
Default policy: custom — the endpoint authenticates the caller itself.
| Methods | Path |
|---|---|
| GET | /bff/runs/{run_id}/events/stream |
| GET | /runs/{run_id}/monitors/stream |
run:view
Browse runs, their events, monitors and monitor samples, and download run artifacts.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /runs/{run_id}/artifacts/{artifact_id}/download |
| GET | /runs/{run_id}/monitors/{monitor_id}/samples |
| GET | /runs/{run_id}/artifacts/download-all |
| GET | /runs/{run_id}/monitors |
| GET | /runs/{run_id}/events |
| GET | /runs/filter-options |
| GET | /runs/{run_id}/tree |
| GET | /runs/{run_id}/monitors/{monitor_id} |
| GET | /runs/{run_id} |
| GET | /runs |
run:trigger
Start a run.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| POST | /runs |
run:control
Cancel, pause, resume and rename runs; soft-delete and restore them.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| POST | /runs/{run_id}/window/start-now |
| POST | /runs/{run_id}/restore |
| POST | /runs/{run_id}/cancel |
| POST | /runs/{run_id}/resume |
| POST | /runs/{run_id}/window |
| POST | /runs/{run_id}/pause |
| PATCH | /runs/{run_id} |
| DELETE | /runs/{run_id} |
run:purge
Permanently delete runs.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /runs/{run_id}/permanent |
approval
approval:view
Browse pending and historical approval requests.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /approvals/node-defaults |
| GET | /runs/{run_id}/approvals |
| GET | /approvals/pending |
| GET | /approvals/{approval_id} |
| GET | /approvals |
approval:decide
Approve or reject an approval request.
Default policy: approver — granted to roles admin, approver.
| Methods | Path |
|---|---|
| POST | /runs/{run_id}/approvals/{approval_id}/decision |
| POST | /approvals/{approval_id}/decision |
site
site:view
Browse sites and the site tree.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /sites/tree |
| GET | /sites/{site_id} |
| GET | /sites |
site:manage
Create, edit, duplicate, soft-delete and restore sites.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /sites/{site_id}/duplicate |
| POST | /sites/{site_id}/restore |
| POST | /sites/bulk/restore |
| POST | /sites/bulk/delete |
| PATCH | /sites/{site_id} |
| DELETE | /sites/{site_id} |
| POST | /sites |
site:purge
Permanently delete sites.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /sites/{site_id}/permanent |
| POST | /sites/bulk/permanent |
device
device:view
Browse and search devices.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /devices/search/ids |
| GET | /devices/search |
| GET | /devices/{device_id} |
| GET | /devices |
device:manage
Create, edit, duplicate, soft-delete and restore devices.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /devices/{device_id}/duplicate |
| POST | /devices/{device_id}/restore |
| POST | /devices/bulk/restore |
| POST | /devices/bulk/delete |
| PUT | /devices/{device_id} |
| DELETE | /devices/{device_id} |
| POST | /devices |
device:annotate
Set the local overlay beside a provider-sourced device's own data - the local tags and the maintenance-state override - without touching what the provider reports.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| PATCH | /devices/{device_id}/overlay |
device:purge
Permanently delete devices.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /devices/{device_id}/permanent |
| POST | /devices/bulk/permanent |
inventory_object
inventory_object:view
Browse generic inventory objects, their object types and the registered provider types.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| GET | /inventory/objects/{object_type}/resolve |
| GET | /inventory/object-types/counts |
| GET | /inventory/provider-types |
| GET | /inventory/object-types |
| GET | /inventory/objects/{object_type}/{object_id} |
| GET | /inventory/objects/{object_type} |
inventory_provider
inventory_provider:view
Read inventory provider configurations (credentials redacted), their sync history and per-provider imported-inventory counts.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /inventory/providers/{provider_id}/sync-history |
| GET | /inventory/provider-inventory |
| GET | /inventory/providers |
| GET | /inventory/providers/{provider_id} |
inventory_provider:manage
Create, edit, soft-delete and restore inventory provider configurations.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /inventory/providers/{provider_id}/discover |
| POST | /inventory/providers/{provider_id}/restore |
| POST | /inventory/providers |
| PATCH | /inventory/providers/{provider_id} |
| DELETE | /inventory/providers/{provider_id} |
inventory_provider:test
Test connectivity to an inventory provider using its stored credentials.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /inventory/providers/{provider_id}/test-connection |
inventory_provider:sync
Run a full sync from a provider now; creates, updates, restores and marks stale the devices, sites and objects imported from it.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /inventory/providers/{provider_id}/sync |
inventory_provider:purge
Permanently delete a soft-deleted provider, or hard-delete every device, site, object and sync-history row it imported (irreversible).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /inventory/providers/{provider_id}/purge-inventory |
| DELETE | /inventory/providers/{provider_id}/permanent |
worker
worker:view
Read the worker registry.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /workers |
flow
flow:view
Browse flows and their committed versions, preview YAML, validate definitions, render the launch form and resolve its option sources, and read step-handler documentation.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /flows/step-handler-types/{handler_id}/docs |
| POST | /flows/{flow_id}/interface/preview-resolve |
| POST | /flows/{flow_id}/interface/validate |
| POST | /flows/{flow_id}/interface/options |
| GET | /flows/{flow_id}/versions/compare |
| GET | /flows/{flow_id}/versioning-info |
| GET | /flows/{flow_id}/launch-contract |
| GET | /flow-interface/option-sources |
| GET | /flows/{flow_id}/yaml-preview |
| GET | /flow-interface/field-types |
| GET | /flows/{flow_id}/interface |
| POST | /flows/{flow_id}/validate |
| GET | /flows/{flow_id}/versions |
| GET | /flows/{flow_id}/versions/{version} |
| GET | /flows/{flow_id} |
| GET | /flows |
flow:manage
Create, edit and duplicate flows; save, revert and load an earlier version into their drafts; soft-delete and restore flows.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/revert-draft |
| PATCH | /flows/{flow_id}/manual-runs |
| POST | /flows/{flow_id}/yaml/check |
| POST | /flows/{flow_id}/duplicate |
| POST | /flows/{flow_id}/restore |
| POST | /flows/{flow_id}/draft |
| PUT | /flows/{flow_id}/yaml |
| PATCH | /flows/{flow_id}/pin |
| POST | /flows/{flow_id}/restore/{version} |
| PUT | /flows/{flow_id} |
| DELETE | /flows/{flow_id} |
| POST | /flows |
flow:commit
Commit the current draft as a new published version.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/commit |
flow:purge
Permanently delete flows.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /flows/{flow_id}/permanent |
flow_attachment
flow_attachment:view
Browse and download flow attachments.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /flows/{flow_id}/attachments/{attachment_id}/download |
| GET | /flows/{flow_id}/attachments |
| GET | /flows/{flow_id}/attachments/{attachment_id} |
flow_attachment:manage
Upload, edit, rename, move and delete flow attachments and attachment folders.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/attachments/bulk-rename |
| POST | /flows/{flow_id}/attachments/bulk |
| POST | /flows/{flow_id}/attachments |
| PATCH | /flows/{flow_id}/attachments/{attachment_id} |
| DELETE | /flows/{flow_id}/attachments/{attachment_id} |
flow_subscription
flow_subscription:view
Read a flow's notification subscriptions.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /flows/{flow_id}/notifications/subscriptions |
flow_subscription:manage
Create, edit and delete a flow's notification subscriptions.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/notifications/subscriptions |
| PATCH | /flows/{flow_id}/notifications/subscriptions/{subscription_id} |
| DELETE | /flows/{flow_id}/notifications/subscriptions/{subscription_id} |
flow_git
flow_git:view
Read a flow's git sync history.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /flows/{flow_id}/git-sync-history |
flow_git:manage
Link a flow to a git repository path, detach it, and pull from the repository; a pull overwrites the definition and can discard an uncommitted draft.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/sync-from-git |
| POST | /flows/{flow_id}/git/detach |
| PATCH | /flows/{flow_id}/git |
flow_git:push
Commit and push a flow's committed version to its git remote (force may overwrite the remote branch).
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /flows/{flow_id}/push-to-git |
schedule
schedule:view
Browse schedules and validate cron expressions.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| POST | /schedules/validate-cron |
| GET | /schedules/{schedule_id} |
| GET | /schedules |
schedule:manage
Create, edit, soft-delete and restore schedules.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /schedules/{schedule_id}/restore |
| PATCH | /schedules/{schedule_id} |
| DELETE | /schedules/{schedule_id} |
| POST | /schedules |
schedule:trigger
Run a schedule immediately.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| POST | /schedules/{schedule_id}/run |
schedule:purge
Permanently delete schedules.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /schedules/{schedule_id}/permanent |
webhook
webhook:view
Browse webhook endpoints, including each endpoint's public trigger path token and allowed-source-IP list.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /webhooks/{webhook_id} |
| GET | /webhooks |
webhook:manage
Create, edit, soft-delete and restore webhook endpoints, and dry-run validate an endpoint's configuration (nothing is sent, no run is created).
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /webhooks/{webhook_id}/restore |
| POST | /webhooks/{webhook_id}/test |
| PATCH | /webhooks/{webhook_id} |
| DELETE | /webhooks/{webhook_id} |
| POST | /webhooks |
webhook:rotate_secret
Re-point a webhook endpoint at a different existing secret for HMAC/bearer verification.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /webhooks/{webhook_id}/rotate-secret |
webhook:purge
Permanently delete webhook endpoints.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /webhooks/{webhook_id}/permanent |
webhook:receive
Public trigger URL called by external systems.
Default policy: public — no authentication required.
| Methods | Path |
|---|---|
| POST | /hooks/{path_token} |
webhook_delivery
webhook_delivery:view
Inspect a webhook's delivery log: source IP, signature result, response status, run ids and a payload hash (never payload bodies).
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| GET | /webhooks/{webhook_id}/deliveries |
notification_destination
notification_destination:view
Browse notification destinations and destination types, including each destination's full configuration (credentials appear only as secret references).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /notifications/destination-types |
| GET | /notifications/flow-defaults |
| GET | /notifications/destinations |
| GET | /notifications/destinations/{destination_id} |
notification_destination:manage
Create, edit, duplicate, soft-delete and restore notification destinations.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /notifications/destinations/{destination_id}/duplicate |
| POST | /notifications/destinations/{destination_id}/restore |
| POST | /notifications/destinations |
| PATCH | /notifications/destinations/{destination_id} |
| DELETE | /notifications/destinations/{destination_id} |
notification_destination:test
Dispatch a real test message to a saved destination or an ad-hoc configuration; the worker resolves embedded secret() references before sending.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /notifications/destinations/{destination_id}/test |
| POST | /notifications/destinations/test-config |
notification_destination:purge
Permanently delete notification destinations.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /notifications/destinations/{destination_id}/permanent |
secret
secret:view
Browse secret references and providers. Values are never returned, but reading a secret performs a live read against its backend to list key names.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /secrets/step-writes |
| GET | /secrets/providers |
| GET | /secrets/{secret_id} |
| GET | /secrets |
secret:discover
List secrets that exist in a backend but were not created via Hegemony (names only).
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| GET | /secrets/discovered |
secret:manage
Create and edit secrets, writing their values into the external backend; delete secrets, which also removes them from the backend (no restore).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /secrets/{secret_id}/duplicate |
| PATCH | /secrets/{secret_id} |
| DELETE | /secrets/{secret_id} |
| POST | /secrets |
secret:step_writes
Let steps of the organization's flows write secrets (secret.write) and name the path prefixes they may read, write and delete; such a step can replace or destroy any secret under those prefixes.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| PUT | /secrets/step-writes |
tf_state
tf_state:view
Browse managed Terraform/OpenTofu states: names, versions, sizes and who holds a lock. Never the state documents themselves.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /tf-states/{name}/versions |
| GET | /tf-states/{name}/events |
| GET | /tf-states/{name} |
| GET | /tf-states |
tf_state:read
Read and download managed state documents, which can hold resource secrets (the HTTP backend's read). A tf.plan or tf.apply step's token acts with the editor role: allocating this above editor, or disabling it, also refuses those steps.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| GET | /tf-states/{name}/versions/{version}/content |
| GET | /tf-states/{name}/state |
tf_state:write
Write, lock and unlock managed states (the HTTP backend), import a state file as a new state, and roll a state back to an earlier version. Forcing another holder's lock (tofu force-unlock) also needs tf_state:manage. A tf.plan or tf.apply step's token acts with the editor role: allocating this above editor, or disabling it, also refuses those steps.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /tf-states/{name}/rollback |
| POST | /tf-states/{name}/import |
| POST | /tf-states/{name}/state |
| DELETE, POST | /tf-states/{name}/lock |
tf_state:manage
Force-unlock a state held by someone else (here or with tofu force-unlock), and delete a state with all its versions (no restore).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /tf-states/{name}/force-unlock |
| DELETE | /tf-states/{name} |
secret_backend
secret_backend:view
Browse secret backend configurations and backend types; the detail view includes the store address and credential env/file names (never values).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /settings/secret-backend-types |
| GET | /settings/secrets-backends |
| GET | /settings/secrets-backends/{backend_id} |
secret_backend:manage
Create, edit and delete secret backends; editing a backend can repoint where every secret() reference resolves.
Default policy: admin — granted to roles admin. Every route needs a fresh sign-in (step-up authentication).
| Methods | Path |
|---|---|
| POST | /settings/secrets-backends |
| PATCH | /settings/secrets-backends/{backend_id} |
| DELETE | /settings/secrets-backends/{backend_id} |
secret_backend:test
Run a backend's connectivity and authentication self-test against the external store.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /settings/secrets-backends/{backend_id}/test |
secret_backend:browse
List item and vault names inside a backend's external store (names only, never values).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /settings/secrets-backends/{backend_id}/items |
variable
variable:view
Browse variables.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /variables/{variable_id} |
| GET | /variables |
variable:manage
Create, edit, soft-delete and restore variables.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /variables/{variable_id}/restore |
| PATCH | /variables/{variable_id} |
| DELETE | /variables/{variable_id} |
| POST | /variables |
variable:purge
Permanently delete variables.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /variables/{variable_id}/permanent |
variable_context
variable_context:view
Editor support for the variable picker: list variables, secret key names, environment-variable names and step outputs, and dry-run validate templates (never values).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| POST | /variable-contexts/validate |
| GET | /variable-contexts |
| POST | /variable-contexts |
file_repository
file_repository:view
Browse file repositories, their kinds and folders.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /file-repositories/{file_repository_id}/folders |
| GET | /file-repositories/kinds |
| GET | /file-repositories/{file_repository_id} |
| GET | /file-repositories |
file_repository:manage
Create, edit, delete and set the default file repository; editing endpoint, bucket or credentials repoints where the org's files are stored.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /file-repositories/{file_repository_id}/set-default |
| POST | /file-repositories/ensure-default |
| PATCH | /file-repositories/{file_repository_id} |
| DELETE | /file-repositories/{file_repository_id} |
| POST | /file-repositories |
file_repository:test
Test connectivity to a file repository.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /file-repositories/{file_repository_id}/test-connection |
registry_credential
registry_credential:view
List the organization's logins for external container registries (host, username and the password's secret reference, never its value).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /registry-credentials/{credential_id} |
| GET | /registry-credentials |
registry_credential:manage
Add, edit and delete registry logins; container steps in the organization use them automatically when pulling images from that registry host.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| PATCH | /registry-credentials/{credential_id} |
| DELETE | /registry-credentials/{credential_id} |
| POST | /registry-credentials |
registry_credential:test
Try a registry login against the registry.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /registry-credentials/{credential_id}/test |
trusted_ca
trusted_ca:view
List the CA certificates the organization trusts for TLS beyond the system store (certificates are public; no secret is shown).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /trusted-cas/{ca_id} |
| GET | /trusted-cas |
trusted_ca:manage
Add, rename and remove the organization's trusted CAs. Steps of the organization's runs that verify TLS trust them, so adding one lets a private CA's servers pass as trusted.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| PATCH | /trusted-cas/{ca_id} |
| DELETE | /trusted-cas/{ca_id} |
| POST | /trusted-cas |
ssh_host_key
ssh_host_key:view
List the SSH host keys the organization trusts for its devices and jump hosts, and how steps check them (the mode).
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /ssh-host-keys/exemptions |
| GET | /ssh-host-keys/refused |
| GET | /ssh-host-keys/policy |
| GET | /ssh-host-keys |
ssh_host_key:manage
Pin and forget trusted SSH host keys. Forgetting a host's key lets the next step that connects trust whatever key the host then presents.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| DELETE | /ssh-host-keys/{key_id} |
| POST | /ssh-host-keys |
ssh_host_key:accept
Accept the key a host presented when a step refused it, after its key changed on purpose (reinstalled, keys rotated). The key replaces the host's trusted keys; only the key the host presented can be accepted. In strict mode, only a member who may also pin keys accepts one.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| POST | /ssh-host-keys/accept |
ssh_host_key:policy
Choose how steps check SSH host keys: learn on first contact, accept only pinned keys, or check nothing at all (switching verification off). Also exempt hosts whose key may change, such as a lab's: steps then store whatever key such a host presents.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /ssh-host-keys/exemptions |
| PUT | /ssh-host-keys/policy |
| DELETE | /ssh-host-keys/exemptions/{exemption_id} |
file
file:view
Browse, download and inspect usage of stored files, including minting time-limited presigned download URLs that work without authentication.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| POST | /files/{file_id}/download-url |
| GET | /files/{file_id}/download |
| GET | /files/{file_id}/usage |
| GET | /files/{file_id}/{filename} |
| GET | /files/{file_id} |
| GET | /files |
file:link_download
Download one file through a link a running step issued for a target (a device or server staging the file). The short-lived token in the link's path is the only credential and opens that one file.
Default policy: public — no authentication required.
| Methods | Path |
|---|---|
| GET | /dl/{token}/{filename} |
file:manage
Upload files, import files from a URL fetched by the server, manage folders, move files, and permanently delete files (no soft-delete).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /file-repositories/{file_repository_id}/folders/rename |
| POST | /file-repositories/{file_repository_id}/files/upload |
| POST | /file-repositories/{file_repository_id}/files/import |
| POST | /file-repositories/{file_repository_id}/folders |
| DELETE | /file-repositories/{file_repository_id}/folders |
| POST | /files/{file_id}/move |
| DELETE | /files/{file_id} |
git_repository
git_repository:view
Browse git repositories and their sync history, and read the tree and file contents of the remote (any path or branch) using the stored credentials.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /git-repositories/{repo_id}/sync-history |
| GET | /git-repositories/{repo_id}/tree |
| GET | /git-repositories/{repo_id}/file |
| GET | /git-repositories/{repo_id} |
| GET | /git-repositories |
git_repository:manage
Create, edit and soft-delete git repositories; editing the URL, branch or credentials redirects every linked flow's pulls and pushes.
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| PATCH | /git-repositories/{repo_id} |
| DELETE | /git-repositories/{repo_id} |
| POST | /git-repositories |
git_repository:test
Test connectivity and credentials of a git repository (shallow clone).
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /git-repositories/{repo_id}/test-connection |
git_repository:sync
Pull-sync every flow linked to a repository in one operation (force can overwrite dirty drafts).
Default policy: editor — granted to roles admin, editor.
| Methods | Path |
|---|---|
| POST | /git-repositories/{repo_id}/sync |
binary_artifact
binary_artifact:view
Browse storage usage of binary run artifacts across all runs and download them in bulk.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /binary-artifacts/bulk-download |
| GET | /binary-artifacts |
binary_artifact:purge
Permanently delete binary artifact content from object storage (no restore).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /binary-artifacts/bulk-delete |
| DELETE | /binary-artifacts/{artifact_id} |
dashboard
dashboard:view
Home-page aggregate of the active organization's runs, flows and devices; every figure is viewer-visible through the list endpoints it summarizes.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /dashboard/stats |
dashboard:org_health
Health roll-up of the caller's own organization (members, activity, approvals, schedules, inventory sync).
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /dashboard/org-health |
api_token
api_token:manage
Issue personal access tokens (plaintext shown once) and list and revoke tokens, including every token owned by a user.
Default policy: admin — granted to roles admin. The routes marked below need a fresh sign-in (step-up authentication).
| Methods | Path | Fresh sign-in |
|---|---|---|
| DELETE | /api-tokens/by-user/{username} | |
| DELETE | /api-tokens/{token_id} | |
| POST | /api-tokens | yes |
| GET | /api-tokens |
audit_log
audit_log:view
Read-only access to the audit log, its statistics and each object's history. Organization members see their active organization's entries only; a platform admin sees every organization's entries and the platform's own.
Default policy: auditor — granted to roles admin, auditor, editor, operator.
| Methods | Path |
|---|---|
| GET | /audit-logs/filter-options |
| GET | /audit-logs/stats |
| GET | /audit-logs/resource/{resource_type}/{resource_id} |
| GET | /audit-logs/{audit_id} |
| GET | /audit-logs |
audit_log:cleanup
Delete audit-log entries older than the retention window across every organization; platform-scoped so an organization admin cannot satisfy it.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /audit-logs/cleanup |
permission
permission:manage
Read the effective route and action permission matrix and set or clear overrides, including which actions ask for a fresh sign-in; holders can grant any role any overridable capability.
Default policy: admin — granted to roles admin. Pinned: no override may reallocate this action or pin one of its routes. The routes marked below need a fresh sign-in (step-up authentication).
| Methods | Path | Fresh sign-in |
|---|---|---|
| PUT | /settings/permissions/actions/override | yes |
| DELETE | /settings/permissions/actions/override | yes |
| PUT | /settings/permissions/actions/step-up | yes |
| DELETE | /settings/permissions/actions/step-up | yes |
| PUT | /settings/permissions/override | yes |
| DELETE | /settings/permissions/override | yes |
| GET | /settings/permissions/actions | |
| GET | /settings/permissions |
plugin
plugin:view
Read the installed out-of-tree plugins overview, including inventory plugins, and the installed extensions with their switches.
Default policy: operator — granted to roles admin, editor, operator.
| Methods | Path |
|---|---|
| GET | /settings/extensions |
| GET | /inventory/plugins |
| GET | /settings/plugins |
extension
extension:list
See which extensions are enabled on the platform, with the pages and menu entries they describe; the web app builds its navigation from it.
Default policy: authenticated — any authenticated caller.
| Methods | Path |
|---|---|
| GET | /extensions |
extension:manage
Enable or disable an installed extension platform-wide. Enabling runs the extension's own setup code in the API and opens its routes and pages to every organization; disabling closes them at once.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| PUT | /settings/extensions/{extension_id} |
environment_variable
environment_variable:view
Browse environment variable names visible to the API and worker.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /settings/environment-variables |
maintenance_job
maintenance_job:view
Monitor scheduler-owned maintenance jobs.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /settings/maintenance/jobs |
platform_configuration
platform_configuration:view
Read every platform setting and where its value comes from. Secrets are masked and cannot be revealed; other values, such as host names, paths and limits, are shown in full.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /settings/platform-configuration/export |
| GET | /settings/platform-configuration |
platform_configuration:manage
Change editable platform settings from the UI, and reset them to the environment. A stored value wins over the environment variable in every process, including settings that move a security boundary (CORS origins, proxy trust, organization auto-join, inventory provider allow-lists). Secrets and settings the platform needs before it can read its database cannot be changed this way.
Default policy: admin — granted to roles admin. Every route needs a fresh sign-in (step-up authentication).
| Methods | Path |
|---|---|
| DELETE, PUT | /settings/platform-configuration/{key} |
platform
platform:health
Deployment-wide health with cross-tenant counts; platform-scoped so an organization admin cannot satisfy it.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /platform/health |
platform:access_review
Export every user, organization role and personal access token for an access review; platform-scoped so an organization admin cannot satisfy it.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /platform/access-review |
platform_sync
platform_sync:view
Read platform-sync profiles and their runs.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /platform-sync/profiles/{profile_id}/runs |
| GET | /platform-sync/profiles |
| GET | /platform-sync/profiles/{profile_id} |
| GET | /platform-sync/runs/{run_id} |
platform_sync:manage
Create, edit and delete platform-sync profiles.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /platform-sync/profiles |
| PATCH | /platform-sync/profiles/{profile_id} |
| DELETE | /platform-sync/profiles/{profile_id} |
platform_sync:execute
Export platform configuration to the profile's git remote.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /platform-sync/profiles/{profile_id}/export |
config_exchange
config_exchange:view
Read the configuration-exchange schema, families, projection and operation status, and list the flows of an organization that can be copied to another.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /config-exchange/resource-families |
| GET | /config-exchange/transfer/flows |
| GET | /config-exchange/projection |
| GET | /config-exchange/schema |
| GET | /config-exchange/operations/{correlation_id} |
config_exchange:execute
Export the whole platform configuration as YAML (never secret values), and plan or apply a bundle that creates, updates and deletes resources across every family, including secrets and permission overrides. Build the bundle that copies flows from one organization to another.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| POST | /config-exchange/operations/{correlation_id}/cancel |
| POST | /config-exchange/transfer/bundle |
| POST | /config-exchange/operations |
registry
registry:token
The platform registry's token endpoint, which zot sends its clients to. Checks a container step's registry token itself (HTTP Basic) and signs a bearer token for what the step may do: pulls from the step's organization, the shared organization and the global namespace, pushes into the organization's image cache and, for an image-building step, under the organization's own image names; never a delete.
Default policy: custom — the endpoint authenticates the caller itself.
| Methods | Path |
|---|---|
| GET | /registry/token |
image
image:view
Browse the platform registry's images visible from the organization: its own namespace, the shared organization's and the global one, with tags, sizes and pull statistics; and read the image cleanup's retention rules.
Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.
| Methods | Path |
|---|---|
| GET | /images/repositories |
| GET | /images/namespaces |
| GET | /images/repository |
| GET | /images/retention |
image:manage
Delete tags and repositories in the organization's own namespace of the platform registry (cached copies included), import uploaded image archives into it, download its images as archives, and follow those imports.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /images/repository/archive |
| POST | /images/transfers/upload |
| DELETE | /images/repository/tag |
| DELETE | /images/repository |
| GET | /images/transfers |
| GET | /images/transfers/{transfer_id} |
image:manage_global
Delete tags and repositories in the registry's global namespace and read every namespace's usage; import uploaded image archives into the global namespace, download its images as archives, and follow those imports; set the image cleanup's retention rules, preview what they delete in every namespace, and run the cleanup now. Platform admins only: the routes are platform-scoped, so the admin policy means the realm role, not an organization membership.
Default policy: admin — granted to roles admin.
| Methods | Path |
|---|---|
| GET | /platform/images/repository/archive |
| GET | /platform/images/retention/preview |
| POST | /platform/images/transfers/upload |
| DELETE | /platform/images/repository/tag |
| POST | /platform/images/retention/run |
| DELETE | /platform/images/repository |
| GET | /platform/images/transfers |
| PUT | /platform/images/retention |
| GET | /platform/images/usage |
| GET | /platform/images/transfers/{transfer_id} |