Skip to content

Commit d45435b

Browse files
marythoughtclaude
marythought
and
claude
committed
chore(docs): update Java/JS examples to use EntityIdentifier helpers
All three SDKs now ship convenience constructors for EntityIdentifier (Go: ForEmail, Java: EntityIdentifiers.forEmail, JS: forEmail). Update the authorization and discovery docs to use these helpers instead of verbose nested proto/object construction. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 3c2490a commit d45435b

2 files changed

Lines changed: 80 additions & 122 deletions

File tree

‎docs/sdks/authorization.mdx‎

Lines changed: 74 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,26 @@ req := &authorizationv2.GetDecisionRequest{
8888
}
8989
```
9090

91-
**Java** — build the nested proto structure:
91+
**Java** — use the `EntityIdentifiers` helper class:
92+
93+
| Helper | Description |
94+
|--------|-------------|
95+
| `EntityIdentifiers.forEmail(email)` | Identify by email address |
96+
| `EntityIdentifiers.forClientId(clientId)` | Identify by client ID (service account / NPE) |
97+
| `EntityIdentifiers.forUserName(username)` | Identify by username |
98+
| `EntityIdentifiers.forToken(jwt)` | Resolve entity from a JWT token |
99+
100+
```java
101+
import io.opentdf.platform.sdk.EntityIdentifiers;
102+
103+
GetDecisionRequest request = GetDecisionRequest.newBuilder()
104+
.setEntityIdentifier(EntityIdentifiers.forEmail("alice@example.com"))
105+
// ...
106+
.build();
107+
```
108+
109+
<details>
110+
<summary>Without helpers (manual proto construction)</summary>
92111

93112
```java
94113
EntityIdentifier.newBuilder()
@@ -103,7 +122,29 @@ EntityIdentifier.newBuilder()
103122
.build()
104123
```
105124

106-
**JavaScript** — use the `identifier` oneof:
125+
</details>
126+
127+
**JavaScript** — use the named helper functions:
128+
129+
| Helper | Description |
130+
|--------|-------------|
131+
| `forEmail(email)` | Identify by email address |
132+
| `forClientId(clientId)` | Identify by client ID (service account / NPE) |
133+
| `forUserName(username)` | Identify by username |
134+
| `forToken(jwt)` | Resolve entity from a JWT token |
135+
| `withRequestToken()` | Derive entity from the request's Authorization header |
136+
137+
```typescript
138+
import { forEmail } from '@opentdf/sdk';
139+
140+
const response = await platformClient.v2.authorization.getDecision({
141+
entityIdentifier: forEmail('alice@example.com'),
142+
// ...
143+
});
144+
```
145+
146+
<details>
147+
<summary>Without helpers (manual object construction)</summary>
107148

108149
```typescript
109150
{
@@ -126,19 +167,17 @@ EntityIdentifier.newBuilder()
126167
}
127168
```
128169

129-
**Supported entity types:**
170+
</details>
130171

131-
| Type | Go helper | Java setter | JS `case` |
132-
|------|-----------|-------------|-----------|
133-
| Email | `ForEmail(email)` | `.setEmailAddress(email)` | `'emailAddress'` |
134-
| Client ID | `ForClientID(id)` | `.setClientId(id)` | `'clientId'` |
135-
| Username | `ForUserName(name)` | `.setUserName(name)` | `'userName'` |
136-
| JWT Token | `ForToken(jwt)` | `.setToken(Token.newBuilder().setJwt(jwt))` | `'token'` |
137-
| Claims | — | `.setClaims(claims)` | `'claims'` |
138-
| Registered Resource | — | `.setRegisteredResourceValueFqn(fqn)` | `'registeredResourceValueFqn'` |
172+
**Supported entity types:**
139173

140-
- **Claims** are used by the Entity Resolution Service (ERS) for custom claim-based entity resolution.
141-
- **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.
174+
| Type | Go | Java | JavaScript |
175+
|------|-----|------|------------|
176+
| Email | `ForEmail(email)` | `forEmail(email)` | `forEmail(email)` |
177+
| Client ID | `ForClientID(id)` | `forClientId(id)` | `forClientId(id)` |
178+
| Username | `ForUserName(name)` | `forUserName(name)` | `forUserName(name)` |
179+
| JWT Token | `ForToken(jwt)` | `forToken(jwt)` | `forToken(jwt)` |
180+
| Request Token | `WithRequestToken()` | — | `withRequestToken()` |
142181

143182
---
144183

@@ -176,7 +215,7 @@ await platformClient.v2.authorization.getEntitlements({ ... })
176215

177216
| Parameter | Type | Required | Description |
178217
|-----------|------|----------|-------------|
179-
| `entityIdentifier` | `EntityIdentifier` | Yes | The entity to query. In Go, use helpers like `authorizationv2.ForEmail("user@example.com")`. |
218+
| `entityIdentifier` | `EntityIdentifier` | Yes | The entity to query. Use [helpers](#entityidentifier) like `ForEmail(...)` (Go), `EntityIdentifiers.forEmail(...)` (Java), or `forEmail(...)` (JS). |
180219
| `withComprehensiveHierarchy` | `bool` | No | When true, returns all entitled values for attributes with hierarchy rules, propagating down from the entitled value. |
181220

182221
**Example**
@@ -279,18 +318,10 @@ for _, dr := range decisionResponse.GetDecisionResponses() {
279318
<TabItem value="java" label="Java">
280319

281320
```java
321+
import io.opentdf.platform.sdk.EntityIdentifiers;
322+
282323
GetEntitlementsRequest request = GetEntitlementsRequest.newBuilder()
283-
.setEntityIdentifier(
284-
EntityIdentifier.newBuilder()
285-
.setEntityChain(
286-
EntityChain.newBuilder()
287-
.addEntities(
288-
Entity.newBuilder()
289-
.setId("user-bob")
290-
.setEmailAddress("bob@OrgA.com")
291-
)
292-
)
293-
)
324+
.setEntityIdentifier(EntityIdentifiers.forEmail("bob@OrgA.com"))
294325
.build();
295326

296327
GetEntitlementsResponse resp = sdk.getServices()
@@ -308,23 +339,10 @@ for (EntityEntitlements entitlement : resp.getEntitlementsList()) {
308339
<TabItem value="js" label="JavaScript">
309340

310341
```typescript
342+
import { forEmail } from '@opentdf/sdk';
343+
311344
const response = await platformClient.v2.authorization.getEntitlements({
312-
entityIdentifier: {
313-
identifier: {
314-
case: 'entityChain',
315-
value: {
316-
entities: [
317-
{
318-
ephemeralId: 'user-bob',
319-
entityType: {
320-
case: 'emailAddress',
321-
value: 'bob@OrgA.com',
322-
},
323-
},
324-
],
325-
},
326-
},
327-
},
345+
entityIdentifier: forEmail('bob@OrgA.com'),
328346
});
329347

330348
for (const entitlement of response.entitlements) {
@@ -335,20 +353,10 @@ for (const entitlement of response.entitlements) {
335353
To expand hierarchy rules:
336354

337355
```typescript
356+
import { forEmail } from '@opentdf/sdk';
357+
338358
const response = await platformClient.v2.authorization.getEntitlements({
339-
entityIdentifier: {
340-
identifier: {
341-
case: 'entityChain',
342-
value: {
343-
entities: [
344-
{
345-
ephemeralId: 'user-123',
346-
entityType: { case: 'emailAddress', value: 'user@company.com' },
347-
},
348-
],
349-
},
350-
},
351-
},
359+
entityIdentifier: forEmail('user@company.com'),
352360
withComprehensiveHierarchy: true,
353361
});
354362

@@ -398,7 +406,7 @@ await platformClient.v2.authorization.getDecision({ ... })
398406

399407
| Parameter | Type | Required | Description |
400408
|-----------|------|----------|-------------|
401-
| `entityIdentifier` | `EntityIdentifier` | Yes | The entity requesting access. In Go, use helpers like `authorizationv2.ForEmail(...)` or `authorizationv2.ForToken(jwt)`. |
409+
| `entityIdentifier` | `EntityIdentifier` | Yes | The entity requesting access. Use [helpers](#entityidentifier) like `ForEmail(...)` (Go), `EntityIdentifiers.forEmail(...)` (Java), or `forEmail(...)` (JS). |
402410
| `action` | `Action` | Yes | The action being performed (e.g., `decrypt`, `read`). |
403411
| `resource` | `Resource` | Yes | The resource being accessed, identified by attribute value FQNs. |
404412

@@ -534,18 +542,10 @@ for _, dr := range decisionResponse.GetDecisionResponses() {
534542
<TabItem value="java" label="Java">
535543

536544
```java
545+
import io.opentdf.platform.sdk.EntityIdentifiers;
546+
537547
GetDecisionRequest request = GetDecisionRequest.newBuilder()
538-
.setEntityIdentifier(
539-
EntityIdentifier.newBuilder()
540-
.setEntityChain(
541-
EntityChain.newBuilder()
542-
.addEntities(
543-
Entity.newBuilder()
544-
.setId("user-123")
545-
.setEmailAddress("user@company.com")
546-
)
547-
)
548-
)
548+
.setEntityIdentifier(EntityIdentifiers.forEmail("user@company.com"))
549549
.setAction(
550550
Action.newBuilder()
551551
.setName("decrypt")
@@ -580,22 +580,11 @@ if (decision.getDecision() == Decision.DECISION_PERMIT) {
580580
<TabItem value="js" label="JavaScript">
581581

582582
```typescript
583+
import { forEmail } from '@opentdf/sdk';
583584
import { Decision } from '@opentdf/sdk/platform/authorization/v2/authorization_pb.js';
584585

585586
const response = await platformClient.v2.authorization.getDecision({
586-
entityIdentifier: {
587-
identifier: {
588-
case: 'entityChain',
589-
value: {
590-
entities: [
591-
{
592-
ephemeralId: 'user-123',
593-
entityType: { case: 'emailAddress', value: 'user@company.com' },
594-
},
595-
],
596-
},
597-
},
598-
},
587+
entityIdentifier: forEmail('user@company.com'),
599588
action: { name: 'decrypt' },
600589
resource: {
601590
resource: {
@@ -778,20 +767,12 @@ for _, dr := range decisionResponse.GetDecisionResponses() {
778767
<TabItem value="java" label="Java">
779768

780769
```java
770+
import io.opentdf.platform.sdk.EntityIdentifiers;
771+
781772
GetDecisionBulkRequest request = GetDecisionBulkRequest.newBuilder()
782773
.addDecisionRequests(
783774
GetDecisionMultiResourceRequest.newBuilder()
784-
.setEntityIdentifier(
785-
EntityIdentifier.newBuilder()
786-
.setEntityChain(
787-
EntityChain.newBuilder()
788-
.addEntities(
789-
Entity.newBuilder()
790-
.setId("user-123")
791-
.setEmailAddress("user@company.com")
792-
)
793-
)
794-
)
775+
.setEntityIdentifier(EntityIdentifiers.forEmail("user@company.com"))
795776
.setAction(Action.newBuilder().setName("decrypt"))
796777
.addResources(
797778
Resource.newBuilder()
@@ -841,22 +822,12 @@ import GetDecisionsExample from '@site/code_samples/java/get-decisions.mdx';
841822
<TabItem value="js" label="JavaScript">
842823

843824
```typescript
825+
import { forEmail } from '@opentdf/sdk';
826+
844827
const response = await platformClient.v2.authorization.getDecisionBulk({
845828
decisionRequests: [
846829
{
847-
entityIdentifier: {
848-
identifier: {
849-
case: 'entityChain',
850-
value: {
851-
entities: [
852-
{
853-
ephemeralId: 'user-123',
854-
entityType: { case: 'emailAddress', value: 'user@company.com' },
855-
},
856-
],
857-
},
858-
},
859-
},
830+
entityIdentifier: forEmail('user@company.com'),
860831
action: { name: 'decrypt' },
861832
resources: [
862833
{

‎docs/sdks/discovery.mdx‎

Lines changed: 6 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -582,40 +582,27 @@ Entity.newBuilder().setId("e1").setUuid("550e8400-e29b-41d4-a716-446655440000").
582582
<TabItem value="js" label="JavaScript">
583583
584584
```typescript
585+
import { forEmail } from '@opentdf/sdk';
585586
import { PlatformClient } from '@opentdf/sdk/platform';
586587

587588
const platform = new PlatformClient({ ...auth, platformUrl });
588589

589590
const resp = await platform.v2.authorization.getEntitlements({
590-
entityIdentifier: {
591-
identifier: {
592-
case: 'entityChain',
593-
value: {
594-
ephemeralId: 'e1',
595-
entities: [
596-
{
597-
ephemeralId: 'e1',
598-
entityType: { case: 'emailAddress', value: 'alice@example.com' },
599-
},
600-
],
601-
},
602-
},
603-
},
591+
entityIdentifier: forEmail('alice@example.com'),
604592
});
605593

606594
if (resp.entitlements.length > 0) {
607595
console.log("alice's entitlements:", resp.entitlements[0].actionsPerAttributeValueFqn);
608596
}
609597
```
610598

611-
Other supported entity types (placed inside the `entities` array):
599+
Other supported [entity identifier helpers](/sdks/authorization#entityidentifier):
612600

613601
```typescript
614-
// By username
615-
{ ephemeralId: 'e1', entityType: { case: 'userName', value: 'alice' } }
602+
import { forUserName, forClientId } from '@opentdf/sdk';
616603

617-
// By client ID (NPE / service account)
618-
{ ephemeralId: 'e1', entityType: { case: 'clientId', value: 'my-service' } }
604+
forUserName('alice') // By username
605+
forClientId('my-service') // By client ID (NPE / service account)
619606
```
620607

621608
</TabItem>

0 commit comments

Comments
 (0)