Skip to main content

Auth And Access

This page describes the access and permissions module.

Access model​

  • Console users authenticate with OTP and receive JWT tokens.
  • Machine workloads authenticate with API keys.
  • Governance APIs under /v1/* accept JWT or API key.
  • JWT authorization is role-based.
  • API key authorization is scope-based.

This module keeps human sign-in and machine access separate so customers can manage permissions cleanly.

JWT roles​

Roles are normalized to:

  • super_admin
  • billing_admin
  • user

Role capabilities in Console​

super_admin​

  • Full workspace access.
  • Can create assets, groups, and policies.
  • Can delete policies.
  • Can approve and reject approvals.
  • Can create, rotate, and revoke API keys.
  • Can invite members with POST /members.

billing_admin​

  • Read-only governance access in Console.
  • Can view organization settings, usage, assets, groups, policies, approvals, and API keys.
  • Cannot perform governance write actions in Console.

user​

  • Read-only governance access in Console.
  • Can view the same governance surfaces as billing admin.
  • Cannot perform governance write actions in Console.

API key scopes​

Every API key must include at least one scope.

Supported scopes:

  • decision:run
  • assets:read
  • assets:write
  • asset_discovery:write
  • groups:read
  • groups:write
  • policies:read
  • policies:write
  • approvals:read
  • approvals:write
  • usage:read
  • audit:read
  • api_keys:read
  • api_keys:write
  • webhooks:read
  • webhooks:write

Behavior:

  • Key creation validates scopes and rejects invalid values.
  • Key rotation preserves current scopes.
  • Requests without required scopes receive 403 Forbidden.

Endpoint enforcement summary​

JWT-only role-gated endpoints​

  • POST /members requires super_admin.
  • POST /v1/api-keys requires super_admin.
  • POST /v1/api-keys/{id}/rotate requires super_admin.
  • POST /v1/api-keys/{id}/revoke requires super_admin.

Scope-gated governance endpoints​

  • POST /v1/evaluate, POST /v1/proxy/evaluate, POST /v1/playground/decision require decision:run.
  • GET /v1/assets requires assets:read.
  • POST /v1/assets requires assets:write.
  • GET /v1/groups requires groups:read.
  • POST /v1/groups requires groups:write.
  • GET /v1/policies requires policies:read.
  • POST /v1/policies, DELETE /v1/policies/{id} require policies:write.
  • GET /v1/approvals requires approvals:read.
  • POST /v1/approvals/{id}/approve, POST /v1/approvals/{id}/reject require approvals:write.
  • GET /v1/audit, GET /v1/decision-explorer require audit:read.
  • GET /v1/usage requires usage:read.
  • GET /v1/api-keys requires api_keys:read.
  • GET /v1/webhooks requires webhooks:read and super_admin.
  • POST /v1/webhooks, POST /v1/webhooks/{id}/rotate, DELETE /v1/webhooks/{id} require webhooks:write and super_admin.

Webhooks are only available when the workspace's approvals capability is enabled, since webhook delivery exists to notify on approval lifecycle events.

For detailed request/response examples, see API Reference.