Cycles

Appearance

Introspect authenticated credential and return effective capabilities​

GET
/v1/auth/introspect

Returns the effective permissions and derived capabilities for the authenticated credential. Used by admin dashboards and by multi-role dashboards that accept both admin and tenant API keys to determine which pages/features the current user can access.
AUTH: - AdminKeyAuth: returns auth_type="admin", permissions=["*"],
capabilities with all flags true. tenant_id and scope_filter MUST
be absent.

  • ApiKeyAuth: returns auth_type="tenant", permissions=[concrete
    Permission values], tenant_id=<key's tenant>, scope_filter=<key's
    filter if any>, capabilities derived from permissions per the
    NORMATIVE table in AuthIntrospectResponse.capabilities.

CAPABILITIES: - Derived from raw permissions — the frontend uses booleans for UI
gating. Admin auth yields all-true; tenant auth yields a subset
per the published derivation table.

BACKWARD COMPATIBILITY: - Servers that do not implement ApiKeyAuth on this endpoint
(either because they pre-date the tenant-introspect contract,
or because deployment policy disables it) SHOULD return 401 on
ApiKeyAuth. Clients MUST handle 401 gracefully — a 401 on
introspect means "this key has no accessible dashboard surface,"
regardless of why.

Authorizations​

AdminKeyAuth

Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.

Type
API Key (header: X-Admin-API-Key)
or
ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

Type
API Key (header: X-Cycles-API-Key)

Responses​

Authentication introspection result

application/json
JSON
{
  
"authenticated": true,
  
"auth_type": "string",
  
"permissions": [
  
  
"string"
  
],
  
"capabilities": {
  
  
"view_overview": true,
  
  
"view_budgets": true,
  
  
"view_events": true,
  
  
"view_webhooks": true,
  
  
"view_audit": true,
  
  
"view_tenants": true,
  
  
"view_api_keys": true,
  
  
"view_policies": true,
  
  
"view_reservations": true,
  
  
"manage_budgets": true,
  
  
"manage_policies": true,
  
  
"manage_webhooks": true,
  
  
"manage_tenants": true,
  
  
"manage_api_keys": true,
  
  
"manage_reservations": true
  
},
  
"tenant_id": "string",
  
"scope_filter": [
  
  
"string"
  
]
}

Playground​

Authorization

Samples​

Powered by VitePress OpenAPI