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 109 actions across 43 resources, in registry order, with the 342 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.

Policies

Policy	Who it grants	Overridable
public	No authentication required	no (structural)
authenticated	Any authenticated caller	yes
viewer	Granted to roles admin, auditor, operator, viewer	yes
auditor	Granted to roles admin, auditor, operator	yes
operator	Granted to roles admin, operator	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.json
GET	/redoc
GET	/docs

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.

Methods	Path
GET	/orgs/{org_ref}/addable-users
POST	/orgs/{org_ref}/members
DELETE, PATCH	/orgs/{org_ref}/members/{user_id}

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/runs/{run_id}/assign-shared-worker
POST	/internal/runs/{run_id}/artifacts/upload
POST	/internal/runs/{run_id}/tf-state-access
POST	/internal/runs/{run_id}/registry-access
GET	/internal/runs/{run_id}/step-outputs
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}/registry-access/{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/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, variables and device download URLs.

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
POST	/files/{file_id}/device-download-url
GET	/internal/runs/{run_id}/attachments
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: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, 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}/monitors/{monitor_id}
GET	/runs/{run_id}
GET	/runs

run:trigger

Start a run.

Default policy: operator — granted to roles admin, 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, operator.

Methods	Path
POST	/runs/{run_id}/restore
POST	/runs/{run_id}/cancel
POST	/runs/{run_id}/resume
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, 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, 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, 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, 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, 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, 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, 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: operator — granted to roles admin, operator.

Methods	Path
POST	/flows/{flow_id}/revert-draft
PATCH	/flows/{flow_id}/manual-runs
POST	/flows/{flow_id}/duplicate
POST	/flows/{flow_id}/restore
POST	/flows/{flow_id}/draft
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: operator — granted to roles admin, operator.

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, 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: operator — granted to roles admin, operator.

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, operator, viewer.

Methods	Path
GET	/flows/{flow_id}/notifications/subscriptions

flow_subscription:manage

Create, edit and delete a flow's notification subscriptions.

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

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, 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: operator — granted to roles admin, operator.

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: operator — granted to roles admin, operator.

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, 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: operator — granted to roles admin, operator.

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, 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, 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: operator — granted to roles admin, operator.

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, 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, 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, operator, viewer.

Methods	Path
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: operator — granted to roles admin, operator.

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

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, operator, viewer.

Methods	Path
GET	/tf-states/{name}/versions
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 operator role: allocating this above operator, or disabling it, also refuses those steps.

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

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 operator role: allocating this above operator, or disabling it, also refuses those steps.

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

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

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, 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, 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, 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, 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

registry

registry:authorize

The platform registry proxy's per-request authorization. Answers only the proxy (a shared secret) and checks a container step's registry token itself: pulls from the step's organization, the shared organization and the global namespace, pushes into the organization's image cache.

Default policy: custom — the endpoint authenticates the caller itself.

Methods	Path
GET	/registry/authorize

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.

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

Methods	Path
GET	/images/repositories
GET	/images/namespaces
GET	/images/repository

image:manage

Delete tags and repositories in the organization's own namespace of the platform registry (cached copies included).

Default policy: admin — granted to roles admin.

Methods	Path
DELETE	/images/repository/tag
DELETE	/images/repository

image:manage_global

Delete tags and repositories in the registry's global namespace and read every namespace's usage. 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
DELETE	/platform/images/repository/tag
DELETE	/platform/images/repository
GET	/platform/images/usage

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, 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: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, 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: operator — granted to roles admin, operator.

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: operator — granted to roles admin, operator.

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: operator — granted to roles admin, operator.

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

Methods	Path
DELETE	/api-tokens/by-user/{username}
DELETE	/api-tokens/{token_id}
POST	/api-tokens
GET	/api-tokens

audit_log

audit_log:view

Browse the audit log and its statistics.

Default policy: admin — granted to roles admin.

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 old audit-log entries.

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

Methods	Path
PUT	/settings/permissions/actions/override
DELETE	/settings/permissions/actions/override
PUT	/settings/permissions/override
DELETE	/settings/permissions/override
GET	/settings/permissions/actions
GET	/settings/permissions

plugin

plugin:view

Read the installed out-of-tree plugins overview, including inventory plugins.

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

Methods	Path
GET	/inventory/plugins
GET	/settings/plugins

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

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_sync

platform_sync:view

Read platform-sync profiles, runs, plans, drift and destructive authorizations.

Default policy: admin — granted to roles admin.

Methods	Path
GET	/platform-sync/profiles/{profile_id}/destructive-authorizations
GET	/platform-sync/profiles/{profile_id}/drift
GET	/platform-sync/profiles/{profile_id}/runs
GET	/platform-sync/profiles
GET	/platform-sync/plans/{plan_id}/families/{family}
GET	/platform-sync/profiles/{profile_id}
GET	/platform-sync/plans/{plan_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, compute drift plans, apply repository state back into the platform and resolve conflicts.

Default policy: admin — granted to roles admin.

Methods	Path
POST	/platform-sync/profiles/{profile_id}/conflicts/{change_id}/resolve
POST	/platform-sync/profiles/{profile_id}/export
POST	/platform-sync/profiles/{profile_id}/apply
POST	/platform-sync/profiles/{profile_id}/plan

platform_sync:authorize_destructive

Grant or revoke the scoped authorizations that allow a destructive platform-sync apply to proceed.

Default policy: admin — granted to roles admin.

Methods	Path
POST	/platform-sync/profiles/{profile_id}/destructive-authorizations/{authorization_id}/revoke
POST	/platform-sync/profiles/{profile_id}/destructive-authorizations

config_exchange

config_exchange:view

Read the configuration-exchange schema, families, projection and operation status.

Default policy: admin — granted to roles admin.

Methods	Path
GET	/config-exchange/resource-families
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.

Default policy: admin — granted to roles admin.

Methods	Path
POST	/config-exchange/operations/{correlation_id}/cancel
POST	/config-exchange/operations