API

Effective Access authorization

Effective Access authorization. This applies the validated business action to the selected tenant or platform resource.

Applies to: Next (0.1 RC1 Preview)
Product revision: 25748655d6be
Audience: Developers and integrators
Source reviewed: 2026-10-06

POST/api/authorization/effective-access

Preview

Effective Access authorization. This applies the validated business action to the selected tenant or platform resource.

Operation ID postapiAuthorizationEffectiveAccess

Operation details

Purpose

Effective Access authorization. This applies the validated business action to the selected tenant or platform resource.

When to use it

Use this when the documented business action or resource creation is the intended next step.

When not to use it

Do not repeat the request blindly after an uncertain outcome. Read the resulting resource or background operation state first.

Contract

Availability

Product version: Next Product release
Licence: An active Product licence is required except for health, authentication, and licence remediation operations.
Entitlements: None
Service roles: core
Deployment: customer managed installation
Feature state: preview

Security

Access

Sign in: Use a session cookie or Bearer session token.

Actor: Authenticated Pūnaha actor authorised for the selected tenant and resource
Permission: None
Resource
Tenant rule: Tenant scoped unless the selected actor is performing an explicitly documented platform action. The x organization id header or authenticated session context selects the tenant. It does not grant access.
Explicit deny: An applicable explicit deny overrides an allow. Knowing or supplying a resource identifier never grants access.

Address, query and header fields

Field	Location	Presence	Type	Meaning	Limits and example
`x-request-id`	header	Optional	string	Optional caller supplied correlation identifier. Pūnaha returns the effective value in the response header.	Minimum length: 1. Maximum length: 200. Example: example request 001

Request body

Content type: application/json. Presence: Required.

Operation request. Every property documents omission, null, sensitivity, source, mutability, availability, access, and lifecycle semantics through JSON Schema and x punaha-* annotations.

Request fields6 documented fields

Request fields

Field	Presence	Type	Meaning	Empty and default	Limits and example	Access, sensitivity and lifecycle
`limit`	optional	integer in `int64` format	The limit associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`offset`	optional	integer in `int64` format	The offset associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`permission`	optional	JSON value	A JSON value whose structure is defined by the selected operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`resourceType`	required	string	The resource type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`subjectId`	required	string	The subject id associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`subjectType`	required	string	The subject type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.

Complete representative request using synthetic data

{
  "limit": 1,
  "offset": 1,
  "permission": "example-value",
  "resourceType": "example-value",
  "subjectId": "example-value",
  "subjectType": "example-value"
}

Smallest schema valid request

{
  "resourceType": "example-value",
  "subjectId": "example-value",
  "subjectType": "example-value"
}

Responses

Status	Meaning and correction boundary	Body
`200`	The operation completed and the response contains the current operation specific representation.	`application/json`, object
`400`	The operation failed with HTTP 400. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`401`	The operation failed with HTTP 401. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`403`	The operation failed with HTTP 403. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`409`	The operation failed with HTTP 409. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`423`	The operation failed with HTTP 423. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`500`	The operation failed with HTTP 500. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`
`503`	The operation failed with HTTP 503. Inspect error.code and error.details, apply the documented correction, and retain x request id.	`application/json`, `APIError`

200 response fields54 documented fields

200 response fields

Field	Presence	Type	Meaning	Empty and default	Limits and example	Access, sensitivity and lifecycle
`data`	required	`HttpapieffectiveAccessResponseResponse`	The operation specific result.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pageSummary`	required	`HttpapieffectiveAccessSummaryResponse`	The page summary associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pageSummary.allowedActions`	required	integer in `int64` format	The allowed actions associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pageSummary.explicitDenies`	required	integer in `int64` format	The explicit denies associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pageSummary.inactiveAssignments`	required	integer in `int64` format	The inactive assignments associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pageSummary.notAllowedActions`	required	integer in `int64` format	The not allowed actions associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pagination`	required	`HttpapieffectiveAccessPaginationResponse`	The pagination associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pagination.limit`	required	integer in `int64` format	The limit associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pagination.offset`	required	integer in `int64` format	The offset associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.pagination.total`	required	integer in `int64` format	The total associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: 1	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resourceType`	required	`HttpapieffectiveAccessResourceTypeResponse`	The resource type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resourceType.area`	required	string	The area associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resourceType.code`	required	string	A stable machine readable code for the represented condition.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resourceType.label`	required	string	The label associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resourceType.pluralLabel`	required	string	The plural label associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources`	required	list of `HttpapieffectiveAccessResourceResponse`	The resources associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions`	required	list of `HttpapieffectiveAccessActionResponse`	The actions associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].allowed`	required	boolean	The allowed associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: Yes	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].code`	required	string	A stable machine readable code for the represented condition.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].description`	required	string	The description associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].label`	required	string	The label associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].message`	required	string	A human readable explanation intended to help understand the result.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].reason`	required	one of `explicit_deny`, `inherited_access`, `matching_allow`, `no_matching_access`, `platform_administrator`, `role_and_grant`, `role_permission`, `system_owner`	The reason associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Allowed: explicit_deny, inherited_access, matching_allow, no_matching_access, platform_administrator, role_and_grant, role_permission, system_owner. Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources`	required	list of `HttpapieffectiveAccessSourceResponse`	The sources associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].actionMatch`	optional	string	The action match associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].assignmentId`	optional	string	The assignment id associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].detail`	optional	string	The detail associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].determinesResult`	required	boolean	The determines result associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: Yes	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].effect`	required	string	The effect associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].expiresAt`	optional	string in `date-time` format or null	The expires at associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: 2026 08 28T00:00:00Z	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].inherited`	required	boolean	The inherited associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: Yes	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].name`	required	string	The name associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].overridden`	required	boolean	The overridden associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: Yes	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].relationship`	optional	string	The relationship associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].resourceMatch`	optional	string	The resource match associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].scope`	required	string	The scope associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].sourceType`	required	string	The source type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].status`	required	string	The current lifecycle or processing state.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].actions[].sources[].warning`	optional	string	The warning associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].area`	required	string	The area associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].description`	optional	string	The description associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].name`	required	string	The name associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].parent`	optional	`HttpapiaccessResourceParentResponse` or null	The parent associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].resourceId`	required	string	The resource id associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].resourceType`	required	string	The resource type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].status`	required	string	The current lifecycle or processing state.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.resources[].warning`	optional	string	The warning associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject`	required	`HttpapiaccessExplanationSubjectResponse`	The subject associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	No additional schema limit is listed	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.detail`	optional	string	The detail associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.id`	required	string	The stable identifier of this resource.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.name`	required	string	The name associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.role`	optional	string	The role associated with this resource or operation.	The field may be omitted. Omission is different from null, an empty string, an empty collection, zero, or false. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.status`	required	string	The current lifecycle or processing state.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.
`data.subject.type`	required	string	The type associated with this resource or operation.	The field is present. Empty strings or collections are valid only when the field constraints and operation rules allow them. Default: No client default is assumed unless a JSON Schema default is present.	Example: example value	Inherits the operation access rules. Inherits the operation availability unless an operation specific rule says otherwise. No special sensitivity is marked. No special handling is inferred beyond normal tenant access, audit, retention, and data classification controls. Lifecycle: Next Product release.

Successful response using synthetic data

{
  "data": {
    "pageSummary": {
      "allowedActions": 1,
      "explicitDenies": 1,
      "inactiveAssignments": 1,
      "notAllowedActions": 1
    },
    "pagination": {
      "limit": 1,
      "offset": 1,
      "total": 1
    },
    "resourceType": {
      "area": "example-value",
      "code": "example-value",
      "label": "example-value",
      "pluralLabel": "example-value"
    },
    "resources": [
      {
        "actions": [
          {
            "allowed": true,
            "code": "example-value",
            "description": "example-value",
            "label": "example-value",
            "message": "example-value",
            "reason": "example-value",
            "sources": [
              {
                "actionMatch": "example-value",
                "assignmentId": "example-value",
                "detail": "example-value",
                "determinesResult": true,
                "effect": "example-value",
                "expiresAt": "2026-08-28T00:00:00Z",
                "inherited": true,
                "name": "example-value",
                "overridden": true,
                "relationship": "example-value",
                "resourceMatch": "example-value",
                "scope": "example-value",
                "sourceType": "example-value",
                "status": "example-value",
                "warning": "example-value"
              }
            ]
          }
        ],
        "area": "example-value",
        "description": "example-value",
        "name": "example-value",
        "parent": {
          "id": "example-value",
          "name": "example-value",
          "resourceType": "example-value"
        },
        "resourceId": "example-value",
        "resourceType": "example-value",
        "status": "example-value",
        "warning": "example-value"
      }
    ],
    "subject": {
      "detail": "example-value",
      "id": "example-value",
      "name": "example-value",
      "role": "example-value",
      "status": "example-value",
      "type": "example-value"
    }
  }
}

Effects

Behaviour and other effects

Changes: Validates access and input, then applies the operation specific state change. A failed validation or authorisation check does not intentionally apply the requested change.
Audit events: The mutation is subject to the Product audit policy. The exact event name is operation owned and must be reviewed before publication.
Background work: No background work is inferred. The success response represents completion of the HTTP action.
External effects: No external call is inferred from the route name. Operation specific service behaviour remains authoritative.
Transaction boundary: The HTTP success or error describes the synchronous boundary. Background operations have their own observable lifecycle and may outlive the request.

Operation

Reliability

Idempotent: No
Retry: Do not retry automatically after a timeout or lost response. Read current state first.
Concurrency: Use documented If Match or resource revision fields where exposed. Otherwise read current state before changing it and handle HTTP 409 conflicts.
Consistency: The response reflects the synchronous operation boundary. Background and provider backed state can converge later and must be read through its status operation.
Timeout: Client timeouts do not cancel completed or already started server work unless the operation explicitly supports cancellation.
Request ID: Send or record x request id and retain the returned value for diagnosis.

Errors and corrections

Status	Code	Cause	Correction	Retryable	Partial work
`400`	`ACCESS_RESOURCE_TYPE_UNSUPPORTED`	Choose a resource type from the permission catalogue.	Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help.	No unchanged retry	No requested mutation is expected before this failure boundary.
`400`	`INVALID_REQUEST_BODY`	The request body or supplied field values are invalid.	Correct the named field or rule in error.details, then submit a new request. Retrying an unchanged request will not help.	No unchanged retry	No requested mutation is expected before this failure boundary.
`401`	`AUTHENTICATION_REQUIRED`	A valid authenticated session or supported token is required.	Authenticate again using a supported mechanism and confirm that the credential is current.	No unchanged retry	No requested mutation is expected before this failure boundary.
`403`	`PERMISSION_REQUIRED`	The authenticated actor does not have the exact permission or resource action.	Select the correct tenant and resource, then ask an authorised administrator to grant the exact documented action if appropriate.	No unchanged retry	No requested mutation is expected before this failure boundary.
`409`	`STATE_CONFLICT`	Current resource state or a dependency prevents the requested change.	Read current state, resolve the named dependency or lifecycle conflict, and submit a deliberate new request.	No unchanged retry	The caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
`423`	`LICENCE_REMEDIATION_REQUIRED`	The installation is restricted and permits only licence remediation actions.	Complete the indicated licence or membership remediation before retrying Product work.	No unchanged retry	The caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
`500`	`INTERNAL_ERROR`	Pūnaha could not complete the operation because of an unexpected internal failure.	Retain x request id and the stable error code, avoid blind retries, and investigate the operation or contact support. Code: INTERNAL_ERROR.	No unchanged retry	The caller must read current resource or background operation state before retrying because work may have started before the failure became observable.
`503`	`DEPENDENCY_UNAVAILABLE`	A required node, database, provider, or service is temporarily unavailable.	Retain x request id, check health and the named dependency, then retry with bounded backoff when safe.	Yes, with the documented safeguards	The caller must read current resource or background operation state before retrying because work may have started before the failure became observable.

Code examples

Use a supported credential and synthetic data. Do not disable TLS checks or retry a request that changes state blindly.

cURL example

curl --request POST "$PUNAHA_URL/api/authorization/effective-access" \
  --header "Authorization: Bearer $PUNAHA_TOKEN" \
  --header "x-request-id: example-request-001" \
  --header "Content-Type: application/json" \
  --data '{"limit":1,"offset":1,"permission":"example-value","resourceType":"example-value","subjectId":"example-value","subjectType":"example-value"}'

JavaScript example

const response = await fetch(`${PUNAHA_URL}/api/authorization/effective-access`, {
  method: "POST",
  headers: {
  "x-request-id": "example-request-001",
  "Authorization": "Bearer ${PUNAHA_TOKEN}",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
    "limit": 1,
    "offset": 1,
    "permission": "example-value",
    "resourceType": "example-value",
    "subjectId": "example-value",
    "subjectType": "example-value"
  })
});

if (!response.ok) throw new Error(`Pūnaha request failed: ${response.status}`);
const result = response.status === 204 ? undefined : await response.json();

C# example

using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient { BaseAddress = new Uri(punahaUrl) };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", punahaToken);
using var request = new HttpRequestMessage(HttpMethod.Post, "/api/authorization/effective-access");
request.Headers.Add("x-request-id", "example-request-001");
var json = "{\"limit\":1,\"offset\":1,\"permission\":\"example-value\",\"resourceType\":\"example-value\",\"subjectId\":\"example-value\",\"subjectType\":\"example-value\"}";
request.Content = new StringContent(json, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

PowerShell example

$headers = @{ Authorization = "Bearer $env:PUNAHA_TOKEN"; "x-request-id" = "example-request-001" }
$body = @'
{
  "limit": 1,
  "offset": 1,
  "permission": "example-value",
  "resourceType": "example-value",
  "subjectId": "example-value",
  "subjectType": "example-value"
}
'@
Invoke-RestMethod -Method POST `
  -Uri "$env:PUNAHA_URL/api/authorization/effective-access" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

postapiAuthorizationCheckAccess, next action

Version history

Next Product release: Operation documented from the current registered Go route and handler contract.

Was this page helpful?

Your answer helps us improve the documentation.

Do not include personal information, customer information, passwords, or keys.

Effective Access authorization

Operation details

Purpose

When to use it

When not to use it

Availability

Access

Address, query and header fields

Request body

Request fields

Responses

200 response fields

Behaviour and other effects

Reliability

Errors and corrections

Code examples

Version history

Was this page helpful?

Browse documentation

Choose a version

Search the guides

View the full screenshot

Operation details

Purpose

When to use it

When not to use it

Availability

Access

Address, query and header fields

Request body

Request fields

Responses

200 response fields

Behaviour and other effects

Reliability

Errors and corrections

Code examples

Related APIs

Version history

Was this page helpful?