diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index c620aa8c..afb681cd 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -240,6 +240,58 @@ const response = await platform.v2.authorization.getDecision({ - **Claims** are used by the Entity Resolution Service (ERS) for custom claim-based entity resolution. - **Registered Resource** identifies an entity by a [registered resource](/components/policy/registered_resources) value FQN stored in platform policy, where the resource acts as a single entity for authorization decisions. +### Action + +Every authorization call requires an [`Action`](/sdks/policy#action) — what's being requested (e.g. `read`, `update`). The action must already be defined in policy — a [standard action](/components/policy/actions) or a registered custom one — these helpers construct the reference only; they don't create or validate it. + + + + + + +`authorizationv2.ForAction(name)` constructs an `Action` without importing the `policy` package: + +```go +import authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" + +req := &authorizationv2.GetDecisionRequest{ + Action: authorizationv2.ForAction("read"), + // ... +} +``` + +
+Without helper (manual proto construction) + +```go +import "github.com/opentdf/platform/protocol/go/policy" + +&policy.Action{Name: "read"} +``` + +
+ +
+ + +No helper needed — construct the action directly: + +```java +Action.newBuilder().setName("read").build(); +``` + + + + +No helper needed — construct the action directly: + +```typescript +{ name: 'read' } +``` + + +
+ ### Resource A `Resource` identifies the data being accessed in [GetDecision](#getdecision) and [GetDecisionBulk](#getdecisionbulk) calls. It can be specified as a set of attribute value FQNs (most common — e.g. the attributes on a TDF) or as a [registered resource](/components/policy/registered_resources) value FQN stored in platform policy. @@ -602,7 +654,7 @@ await platform.v2.authorization.getDecision({ ... }) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. Use [helpers](#entityidentifier) like `ForEmail(...)` (Go) or `EntityIdentifiers.forEmail(...)` (Java/JS). | -| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed (e.g., `decrypt`, `read`). Use `ForAction(...)` (Go) to construct one without importing the `policy` package. | +| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed (e.g., `decrypt`, `read`). Use [`ForAction(...)`](#action) (Go) to construct one without importing the `policy` package. | | `resource` | [`Resource`](#resource) | Yes | The resource being accessed. Use [helpers](#resource) like `ForAttributeValues(...)` (Go) or `Resources.forAttributeValues(...)` (Java/JS). | | `fulfillableObligationFqns` | `[]string` | No | Obligation value FQNs the caller (PEP) is able to enforce, e.g. `https:///obl//value/`. The service only returns `DECISION_PERMIT` when every obligation it would require is present in this list; if it would require an obligation you have not declared, it denies. Empty means the caller declares no obligation support. See [obligations](/components/policy/obligations). | @@ -833,7 +885,7 @@ Each `GetDecisionMultiResourceRequest` contains: | Field | Type | Required | Description | |-------|------|----------|-------------| | `entityIdentifier` | [`EntityIdentifier`](#entityidentifier) | Yes | The entity requesting access. | -| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed. Use `ForAction(...)` (Go) to construct one without importing the `policy` package. | +| `action` | [`Action`](/sdks/policy#action) | Yes | The action being performed. Use [`ForAction(...)`](#action) (Go) to construct one without importing the `policy` package. | | `resources` | [`[]Resource`](#resource) | Yes | Resources to evaluate, each with an `ephemeralId` for correlation. | | `fulfillableObligationFqns` | `[]string` | No | Obligation value FQNs the caller (PEP) is able to enforce, applied to every resource in the request. Same semantics as on [GetDecision](#getdecision). |