From 9fb209161a1bdf3a890bd03bca50ea0c1dbf3341 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 11 Aug 2026 09:35:46 -0700 Subject: [PATCH 1/2] docs(sdks): document sdk version for ForAction helper Adds an Action subsection to authorization.mdx (parity with EntityIdentifier/Resource) noting ForAction requires Go SDK v0.30.0+, and links the existing parameter-table mentions to it. --- docs/sdks/authorization.mdx | 56 +++++++++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index c620aa8c..cf2d7641 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. `decrypt`, `read`). + + + + + + +`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("decrypt"), + // ... +} +``` + +
+Without helper (manual proto construction) + +```go +import "github.com/opentdf/platform/protocol/go/policy" + +&policy.Action{Name: "decrypt"} +``` + +
+ + + + +No helper needed — construct the action directly: + +```java +Action.newBuilder().setName("decrypt").build(); +``` + + + + +No helper needed — construct the action directly: + +```typescript +{ name: 'decrypt' } +``` + + + + ### 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). | From c66028f2af3677595f3c49bae926a6e5bbc5130f Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 11 Aug 2026 10:56:14 -0700 Subject: [PATCH 2/2] docs(sdks): use read (not decrypt) in Action examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit decrypt isn't a real action name — read, create, update, delete are the standard actions (docs/components/policy/actions.md); read is what covers TDF decrypt flows. Also clarifies that the action must already be defined in policy — ForAction/manual construction only build the reference, they don't create or validate it. Addresses review from CodeRabbit and jp-ayyappan on PR #384. --- docs/sdks/authorization.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index cf2d7641..afb681cd 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -242,7 +242,7 @@ const response = await platform.v2.authorization.getDecision({ ### Action -Every authorization call requires an [`Action`](/sdks/policy#action) — what's being requested (e.g. `decrypt`, `read`). +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. @@ -255,7 +255,7 @@ Every authorization call requires an [`Action`](/sdks/policy#action) — what's import authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" req := &authorizationv2.GetDecisionRequest{ - Action: authorizationv2.ForAction("decrypt"), + Action: authorizationv2.ForAction("read"), // ... } ``` @@ -266,7 +266,7 @@ req := &authorizationv2.GetDecisionRequest{ ```go import "github.com/opentdf/platform/protocol/go/policy" -&policy.Action{Name: "decrypt"} +&policy.Action{Name: "read"} ``` @@ -277,7 +277,7 @@ import "github.com/opentdf/platform/protocol/go/policy" No helper needed — construct the action directly: ```java -Action.newBuilder().setName("decrypt").build(); +Action.newBuilder().setName("read").build(); ``` @@ -286,7 +286,7 @@ Action.newBuilder().setName("decrypt").build(); No helper needed — construct the action directly: ```typescript -{ name: 'decrypt' } +{ name: 'read' } ```