Skip to content

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 ​

PolicyWho it grantsOverridable
publicNo authentication requiredno (structural)
authenticatedAny authenticated calleryes
viewerGranted to roles admin, auditor, editor, operator, vieweryes
auditorGranted to roles admin, auditor, editor, operatoryes
operatorGranted to roles admin, editor, operatoryes
editorGranted to roles admin, editoryes
approverGranted to roles admin, approveryes
adminGranted to roles adminyes
org_memberAuthorized against the organization named by the route's {org_ref} parameter: platform admins always pass; otherwise the caller needs any membership in that organizationyes
org_adminAuthorized 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 organizationyes
internalWorker 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)
customThe endpoint authenticates the caller itselfno (structural)
disabledNobody — the endpoint is switched off for every caller, platform admins included, until an administrator assigns another policyyes

system ​

system:health ​

Liveness and readiness probes.

Default policy: public — no authentication required.

MethodsPath
GET/health
GET/ready

system:docs ​

Interactive API documentation and the OpenAPI schema.

Default policy: public — no authentication required.

MethodsPath
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.

MethodsPath
GET/system/version

auth ​

auth:config ​

OIDC discovery for the UI and BFF ticket validation.

Default policy: public — no authentication required.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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).

MethodsPathFresh sign-in
GET/orgs/{org_ref}/addable-users
POST/orgs/{org_ref}/membersyes
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.

MethodsPath
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).

MethodsPath
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).

MethodsPath
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).

MethodsPath
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).

MethodsPath
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).

MethodsPath
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).

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
POST/runs

run:control ​

Cancel, pause, resume and rename runs; soft-delete and restore them.

Default policy: operator — granted to roles admin, editor, operator.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
PATCH/devices/{device_id}/overlay

device:purge ​

Permanently delete devices.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
POST/flows/{flow_id}/commit

flow:purge ​

Permanently delete flows.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
POST/schedules/{schedule_id}/run

schedule:purge ​

Permanently delete schedules.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
POST/webhooks/{webhook_id}/rotate-secret

webhook:purge ​

Permanently delete webhook endpoints.

Default policy: admin — granted to roles admin.

MethodsPath
DELETE/webhooks/{webhook_id}/permanent

webhook:receive ​

Public trigger URL called by external systems.

Default policy: public — no authentication required.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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).

MethodsPath
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.

MethodsPath
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.

MethodsPath
GET/settings/secrets-backends/{backend_id}/items

variable ​

variable:view ​

Browse variables.

Default policy: viewer — granted to roles admin, auditor, editor, operator, viewer.

MethodsPath
GET/variables/{variable_id}
GET/variables

variable:manage ​

Create, edit, soft-delete and restore variables.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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

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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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).

MethodsPathFresh sign-in
DELETE/api-tokens/by-user/{username}
DELETE/api-tokens/{token_id}
POST/api-tokensyes
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.

MethodsPath
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.

MethodsPath
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).

MethodsPathFresh sign-in
PUT/settings/permissions/actions/overrideyes
DELETE/settings/permissions/actions/overrideyes
PUT/settings/permissions/actions/step-upyes
DELETE/settings/permissions/actions/step-upyes
PUT/settings/permissions/overrideyes
DELETE/settings/permissions/overrideyes
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
GET/settings/environment-variables

maintenance_job ​

maintenance_job:view ​

Monitor scheduler-owned maintenance jobs.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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).

MethodsPath
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.

MethodsPath
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.

MethodsPath
GET/platform/access-review

platform_sync ​

platform_sync:view ​

Read platform-sync profiles and their runs.

Default policy: admin — granted to roles admin.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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.

MethodsPath
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}

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].