> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # Explain an access decision > Explains whether the authenticated requester can perform an access action and why. ## OpenAPI ````yaml /openapi-public.json post /access_decisions openapi: 3.1.0 info: title: Akua API version: 1.0.0 description: >- Public API for managing Akua workspaces, clusters, products, and installs. Authenticate with a workspace API token via the `Authorization: Bearer sk_akua_...` header. A workspace-owned token implies its workspace. Broad tokens select the active workspace via the optional `Akua-Context` header. contact: name: Akua API support email: support@akua.dev url: https://akua.dev/docs servers: - url: https://api.akua.dev/v1 description: Production security: [] tags: - name: Auth description: Authentication and token management. - name: Agents description: Agent identities and configuration. - name: Agent sessions description: Durable agent conversations and tasks. - name: Agent turns description: Submitted agent work and event emission. - name: Agent events description: Normalized agent event history and streams. - name: Custom domains description: Workspace custom domains and routing targets. - name: Cloudflare description: Cloudflare account credentials and gateway control. - name: Clusters description: Kubernetes clusters and cluster access operations. - name: ComputeConfigs description: Workspace compute provider configurations. - name: Entitlements description: Effective workspace capabilities and limits. - name: Dashboards description: Dashboard and widget resources. - name: Installs description: Installation and render operations. - name: Machines description: Compute machines and lifecycle events. - name: Notifications description: User notification state. - name: Offer Channels description: Private offer channels and policy versions. - name: Offers description: Marketplace offers and redemption tracking. - name: Operations description: Long-running operation status and controls. - name: Order Drafts description: Draft checkout orders and checkout sessions. - name: Organizations description: Organizations, memberships, and managed workspaces. - name: Packages description: Software packages, versions, and input schemas. - name: Products description: Marketplace product catalog resources. - name: Preview hostnames description: Install preview hostnames and routing state. - name: Quotas description: Workspace quota limits and usage. - name: Regions description: Available deployment regions. - name: Registry description: Container registry credentials and repositories. - name: Repository change requests description: Fork-backed repository change reviews and lifecycle actions. - name: Repositories description: Source repositories available to the workspace. - name: Secrets description: Workspace secrets and secret versions. - name: Snippets description: Reusable snippets and snippet runs. - name: Workspace subdomains description: Workspace subdomain identity. - name: Workspaces description: Workspace resources, members, and billing state. paths: /access_decisions: post: tags: - Access Decisions summary: Explain an access decision description: >- Explains whether the authenticated requester can perform an access action and why. operationId: accessDecisions.explain parameters: - schema: type: string minLength: 1 maxLength: 53 description: >- Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace. example: ws_j572abc123def456 required: false description: >- Optional workspace/scope context for the request. Carries a single workspace wire id (`ws_…`) today. Only needed for broad tokens — a workspace-owned token implies its workspace. name: akua-context in: header requestBody: content: application/json: schema: $ref: '#/components/schemas/ExplainAccessDecisionBody' responses: '200': description: Access decision explanation content: application/json: schema: $ref: '#/components/schemas/AccessDecision' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '422': description: Unprocessable entity content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' security: - BearerAuth: [] components: schemas: ExplainAccessDecisionBody: oneOf: - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offers.create_via_channel resource: $ref: '#/components/schemas/OfferChannelCreateResource' context: $ref: '#/components/schemas/OfferChannelDecisionContext' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offers.create_non_channel_paid_product_offer resource: $ref: '#/components/schemas/NonChannelPaidProductOfferResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offers.create_non_billable_test_offer resource: $ref: '#/components/schemas/NonBillableTestOfferResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offer_channels.create resource: $ref: '#/components/schemas/OfferChannelCreateDecisionResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offer_channels.inspect resource: $ref: '#/components/schemas/OfferChannelInspectResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - channel_policies.approve resource: $ref: '#/components/schemas/ChannelPolicyApproveResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - channel_policies.activate resource: $ref: '#/components/schemas/ChannelPolicyActivateResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offers.approve_channel_offer resource: $ref: '#/components/schemas/OfferChannelModerationResource' context: $ref: '#/components/schemas/OfferChannelDecisionContext' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - offers.reject_channel_offer resource: $ref: '#/components/schemas/OfferChannelModerationResource' context: $ref: '#/components/schemas/OfferChannelDecisionContext' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - workspaces.inspect_class resource: $ref: '#/components/schemas/WorkspaceClassResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - workspaces.inspect_membership resource: $ref: '#/components/schemas/WorkspaceMembershipResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.create resource: $ref: '#/components/schemas/ProductCockpitResource' required: - permission additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.get resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.update resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.archive resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.unarchive resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.inspect_readiness resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.inspect_offer_creation resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.inspect_channels resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - products.inspect_installs resource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - product_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - packages.create resource: $ref: '#/components/schemas/PackageCockpitResource' required: - permission additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - packages.import_published_package resource: $ref: '#/components/schemas/PackageCockpitResource' required: - permission additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - packages.get resource: type: object properties: package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 required: - package_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - package_versions.get resource: type: object properties: package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 required: - package_id - package_version_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - package_versions.inputs resource: type: object properties: package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 required: - package_id - package_version_id - workspace_id additionalProperties: false required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.update resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.delete resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.suspend resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.resume resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.refresh_capabilities resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.get_kubeconfig resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.create_worker_bootstrap resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - clusters.revoke_worker_bootstrap resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - machines.create resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - machines.update resource: $ref: '#/components/schemas/MachineCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - machines.delete resource: $ref: '#/components/schemas/MachineCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - machines.suspend resource: $ref: '#/components/schemas/MachineCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - machines.resume resource: $ref: '#/components/schemas/MachineCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - compute_configs.update resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false - type: object properties: subject: $ref: '#/components/schemas/AccessSubject' permission: type: string enum: - installs.create resource: $ref: '#/components/schemas/ClusterCockpitResource' required: - permission - resource additionalProperties: false AccessDecision: type: object properties: decision: $ref: '#/components/schemas/AccessDecisionResult' action: type: object properties: id: type: string minLength: 1 name: type: string minLength: 1 required: - id - name additionalProperties: false reasons: type: array items: $ref: '#/components/schemas/AccessReason' required: - decision - action - reasons additionalProperties: false ApiErrorResponse: type: object properties: success: type: boolean enum: - false errors: type: array items: $ref: '#/components/schemas/ApiErrorEntry' result: type: object properties: {} description: Always empty for error responses required: - success - errors - result AccessSubject: type: object properties: user_id: type: string minLength: 1 organization_id: type: string minLength: 1 maxLength: 54 workspace_id: type: string minLength: 1 maxLength: 53 additionalProperties: false OfferChannelCreateResource: type: object properties: offer_channel_id: type: string minLength: 1 maxLength: 54 target_workspace_id: type: string minLength: 1 maxLength: 53 product_id: type: string minLength: 1 maxLength: 55 commercial_mode: type: string enum: - paid - non_billable_test required: - offer_channel_id - product_id - commercial_mode additionalProperties: false OfferChannelDecisionContext: type: object properties: selected_organization_id: type: string minLength: 1 maxLength: 54 stripe_mode: type: string enum: - live - test - sandbox additionalProperties: false NonChannelPaidProductOfferResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 product_id: type: string minLength: 1 maxLength: 55 package_version_id: type: string minLength: 1 maxLength: 55 target_workspace_id: type: string minLength: 1 maxLength: 53 commercial_mode: type: string enum: - paid required: - workspace_id - product_id - package_version_id - commercial_mode additionalProperties: false NonBillableTestOfferResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 product_id: type: string minLength: 1 maxLength: 55 package_version_id: type: string minLength: 1 maxLength: 55 target_workspace_id: type: string minLength: 1 maxLength: 53 target_workspace_class: type: string enum: - standard - platform - sandbox commercial_mode: type: string enum: - non_billable_test required: - workspace_id - product_id - package_version_id - commercial_mode additionalProperties: false OfferChannelCreateDecisionResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 product_id: type: string minLength: 1 maxLength: 55 partner_organization_id: type: string minLength: 1 maxLength: 54 required: - workspace_id additionalProperties: false OfferChannelInspectResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 offer_channel_id: type: string minLength: 1 maxLength: 54 product_id: type: string minLength: 1 maxLength: 55 required: - workspace_id additionalProperties: false ChannelPolicyApproveResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 offer_channel_id: type: string minLength: 1 maxLength: 54 channel_policy_id: type: string minLength: 1 maxLength: 56 resource_state: type: string enum: - draft required: - workspace_id - offer_channel_id - channel_policy_id - resource_state additionalProperties: false ChannelPolicyActivateResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 offer_channel_id: type: string minLength: 1 maxLength: 54 channel_policy_id: type: string minLength: 1 maxLength: 56 resource_state: type: string enum: - approved required: - workspace_id - offer_channel_id - channel_policy_id - resource_state additionalProperties: false OfferChannelModerationResource: type: object properties: offer_id: type: string minLength: 1 maxLength: 56 offer_channel_id: type: string minLength: 1 maxLength: 54 owner_workspace_id: type: string minLength: 1 maxLength: 53 resource_state: type: string enum: - pending_approval - approved - rejected required: - offer_id - offer_channel_id - owner_workspace_id - resource_state additionalProperties: false WorkspaceClassResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 required_class: type: string enum: - standard - platform - sandbox required: - workspace_id additionalProperties: false WorkspaceMembershipResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 required_roles: type: array items: type: string enum: - owner - admin - member required: - workspace_id additionalProperties: false ProductCockpitResource: type: object properties: product_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 resource_state: type: string enum: - draft - active - archived required: - workspace_id additionalProperties: false PackageCockpitResource: type: object properties: package_id: type: string minLength: 1 maxLength: 54 package_version_id: type: string minLength: 1 maxLength: 55 workspace_id: type: string minLength: 1 maxLength: 53 required: - workspace_id additionalProperties: false ClusterCockpitResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 required: - workspace_id - cluster_id additionalProperties: false MachineCockpitResource: type: object properties: workspace_id: type: string minLength: 1 maxLength: 53 cluster_id: type: string minLength: 1 maxLength: 54 machine_id: type: string minLength: 1 maxLength: 54 required: - workspace_id - cluster_id - machine_id additionalProperties: false AccessDecisionResult: oneOf: - type: object properties: result: type: string enum: - allowed required: - result additionalProperties: false - type: object properties: result: type: string enum: - denied message: type: string minLength: 1 required: - result - message additionalProperties: false - type: object properties: result: type: string enum: - unknown message: type: string minLength: 1 required: - result - message additionalProperties: false AccessReason: type: object properties: kind: type: string enum: - catalog_default - external_feature_flag - external_billing_entitlement - workspace_access_status - admin_override - policy_rule - quota_limit - quota_usage - quota_override - actor_context - resource_state - workspace_membership - workspace_role - organization_membership - organization_role - workspace_class - resource_ownership - relationship - domain_policy result: type: string enum: - allowed - denied - not_evaluated key: type: string source: type: string message: type: string metric: type: string scope: type: string enum: - global - organization - workspace - user limit: type: number usage: type: number remaining: type: number resourceId: type: string resourceType: type: string relationship: type: string required: - kind - result additionalProperties: false ApiErrorEntry: type: object properties: code: type: integer example: 7002 description: Machine-readable error code message: type: string example: Resource not found description: Human-readable error message path: type: array items: type: string example: - body - name description: Field path that caused the error, when applicable metadata: type: object additionalProperties: type: string required: - code - message securitySchemes: BearerAuth: type: http scheme: bearer description: >- workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens ````