Skip to content

docs(sdks): document sdk version for ForAction helper #384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marythought merged 2 commits into from
Aug 11, 2026
+54 −2
Merged

docs(sdks): document sdk version for ForAction helper #384

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9fb2091
docs(sdks): document sdk version for ForAction helper
marythought Aug 11, 2026
c66028f
docs(sdks): use read (not decrypt) in Action examples
marythought Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 54 additions & 2 deletions docs/sdks/authorization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Tabs>
<TabItem value="go" label="Go">

<SdkVersion language="go" version="0.30.0" source="opentdf" />

`authorizationv2.ForAction(name)` constructs an `Action` without importing the `policy` package:
Comment thread
jp-ayyappan marked this conversation as resolved.

```go
import authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2"

req := &authorizationv2.GetDecisionRequest{
Action: authorizationv2.ForAction("read"),
// ...
}
```

<details>
<summary>Without helper (manual proto construction)</summary>

```go
import "github.com/opentdf/platform/protocol/go/policy"

&policy.Action{Name: "read"}
```

</details>

</TabItem>
<TabItem value="java" label="Java">

No helper needed — construct the action directly:

```java
Action.newBuilder().setName("read").build();
```

</TabItem>
<TabItem value="js" label="JavaScript">

No helper needed — construct the action directly:

```typescript
{ name: 'read' }
```

</TabItem>
</Tabs>

### 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.
Expand Down Expand Up @@ -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://<namespace>/obl/<definition>/value/<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). |

Expand Down Expand Up @@ -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). |

Expand Down
Loading