From 6745ca077f9af03b3cfffaf7216861d10d4474eb Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 31 Mar 2026 14:05:40 -0700 Subject: [PATCH 1/9] docs(sdk): update Go authorization samples to use EntityIdentifier helpers Simplifies the V2 Go code samples for GetDecision and GetEntitlements by using the new sdk.ForClientID helper instead of manual proto nesting. Co-Authored-By: Claude Opus 4.6 (1M context) --- code_samples/authorization/get_decision.mdx | 18 +++------------ .../authorization/get_entitlements.mdx | 22 +++++-------------- 2 files changed, 9 insertions(+), 31 deletions(-) diff --git a/code_samples/authorization/get_decision.mdx b/code_samples/authorization/get_decision.mdx index fb39b751..366d035a 100644 --- a/code_samples/authorization/get_decision.mdx +++ b/code_samples/authorization/get_decision.mdx @@ -16,7 +16,6 @@ import ( "log" authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" - "github.com/opentdf/platform/protocol/go/entity" "github.com/opentdf/platform/protocol/go/policy" "github.com/opentdf/platform/sdk" ) @@ -34,21 +33,10 @@ func main() { } // Get Decision using v2 API + // Use sdk.ForClientID to create an EntityIdentifier in one call. + // Other helpers: sdk.ForEmail, sdk.ForUserName, sdk.ForToken, sdk.WithRequestToken decisionReq := &authorizationv2.GetDecisionRequest{ - EntityIdentifier: &authorizationv2.EntityIdentifier{ - Identifier: &authorizationv2.EntityIdentifier_EntityChain{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{ - { - EphemeralId: "entity-1", - EntityType: &entity.Entity_ClientId{ - ClientId: "opentdf", - }, - }, - }, - }, - }, - }, + EntityIdentifier: sdk.ForClientID("opentdf"), Action: &policy.Action{ Name: "decrypt", }, diff --git a/code_samples/authorization/get_entitlements.mdx b/code_samples/authorization/get_entitlements.mdx index e536918d..1f330ad2 100644 --- a/code_samples/authorization/get_entitlements.mdx +++ b/code_samples/authorization/get_entitlements.mdx @@ -13,8 +13,7 @@ import ( "context" "log" - "github.com/opentdf/platform/protocol/go/authorization" - "github.com/opentdf/platform/protocol/go/entity" + authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" "github.com/opentdf/platform/sdk" ) @@ -33,22 +32,13 @@ func main() { } // Get Entitlements using v2 API - entitlementReq := &authorization.GetEntitlementsRequest{ - EntityIdentifier: &authorization.EntityIdentifier{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{ - { - Id: "entity-1", - EntityType: &entity.Entity_ClientId{ - ClientId: "opentdf", - }, - }, - }, - }, - }, + // Use sdk.ForClientID to create an EntityIdentifier in one call. + // Other helpers: sdk.ForEmail, sdk.ForUserName, sdk.ForToken, sdk.WithRequestToken + entitlementReq := &authorizationv2.GetEntitlementsRequest{ + EntityIdentifier: sdk.ForClientID("opentdf"), } - entitlements, err := client.Authorization.GetEntitlements(context.Background(), entitlementReq) + entitlements, err := client.AuthorizationV2.GetEntitlements(context.Background(), entitlementReq) if err != nil { log.Fatal(err) } From 3ac861922e49eb61a7ee231f33ab8c65f1dd801d Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 31 Mar 2026 17:06:53 -0700 Subject: [PATCH 2/9] docs(sdk): use authorizationv2.ForClientID in code samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates Go authorization samples to use the new EntityIdentifier helpers from the authorizationv2 package — no extra import needed. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- code_samples/authorization/get_decision.mdx | 6 +++--- code_samples/authorization/get_entitlements.mdx | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/code_samples/authorization/get_decision.mdx b/code_samples/authorization/get_decision.mdx index 366d035a..d79a4a76 100644 --- a/code_samples/authorization/get_decision.mdx +++ b/code_samples/authorization/get_decision.mdx @@ -33,10 +33,10 @@ func main() { } // Get Decision using v2 API - // Use sdk.ForClientID to create an EntityIdentifier in one call. - // Other helpers: sdk.ForEmail, sdk.ForUserName, sdk.ForToken, sdk.WithRequestToken + // Use authorizationv2.ForClientID to create an EntityIdentifier in one call. + // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken decisionReq := &authorizationv2.GetDecisionRequest{ - EntityIdentifier: sdk.ForClientID("opentdf"), + EntityIdentifier: authorizationv2.ForClientID("opentdf"), Action: &policy.Action{ Name: "decrypt", }, diff --git a/code_samples/authorization/get_entitlements.mdx b/code_samples/authorization/get_entitlements.mdx index 1f330ad2..1a6ccc53 100644 --- a/code_samples/authorization/get_entitlements.mdx +++ b/code_samples/authorization/get_entitlements.mdx @@ -32,10 +32,10 @@ func main() { } // Get Entitlements using v2 API - // Use sdk.ForClientID to create an EntityIdentifier in one call. - // Other helpers: sdk.ForEmail, sdk.ForUserName, sdk.ForToken, sdk.WithRequestToken + // Use authorizationv2.ForClientID to create an EntityIdentifier in one call. + // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken entitlementReq := &authorizationv2.GetEntitlementsRequest{ - EntityIdentifier: sdk.ForClientID("opentdf"), + EntityIdentifier: authorizationv2.ForClientID("opentdf"), } entitlements, err := client.AuthorizationV2.GetEntitlements(context.Background(), entitlementReq) From 5fae3a363b7973af062af88eca1ba8f3298afb6c Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 31 Mar 2026 17:12:32 -0700 Subject: [PATCH 3/9] docs(sdk): alias import as authorization in Go code samples Uses `authorization` instead of `authorizationv2` as the import alias for cleaner calling convention: authorization.ForClientID("opentdf"). Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- code_samples/authorization/get_decision.mdx | 16 ++++++++-------- code_samples/authorization/get_entitlements.mdx | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/code_samples/authorization/get_decision.mdx b/code_samples/authorization/get_decision.mdx index d79a4a76..dd602336 100644 --- a/code_samples/authorization/get_decision.mdx +++ b/code_samples/authorization/get_decision.mdx @@ -15,7 +15,7 @@ import ( "context" "log" - authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" + authorization "github.com/opentdf/platform/protocol/go/authorization/v2" "github.com/opentdf/platform/protocol/go/policy" "github.com/opentdf/platform/sdk" ) @@ -33,16 +33,16 @@ func main() { } // Get Decision using v2 API - // Use authorizationv2.ForClientID to create an EntityIdentifier in one call. + // Use authorization.ForClientID to create an EntityIdentifier in one call. // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken - decisionReq := &authorizationv2.GetDecisionRequest{ - EntityIdentifier: authorizationv2.ForClientID("opentdf"), + decisionReq := &authorization.GetDecisionRequest{ + EntityIdentifier: authorization.ForClientID("opentdf"), Action: &policy.Action{ Name: "decrypt", }, - Resource: &authorizationv2.Resource{ - Resource: &authorizationv2.Resource_AttributeValues_{ - AttributeValues: &authorizationv2.Resource_AttributeValues{ + Resource: &authorization.Resource{ + Resource: &authorization.Resource_AttributeValues_{ + AttributeValues: &authorization.Resource_AttributeValues{ Fqns: []string{"https://opentdf.io/attr/role/value/developer"}, }, }, @@ -56,7 +56,7 @@ func main() { decisionResult := decision.GetDecision() log.Printf("Decision: %v", decisionResult.GetDecision()) - if decisionResult.GetDecision() == authorizationv2.Decision_DECISION_PERMIT { + if decisionResult.GetDecision() == authorization.Decision_DECISION_PERMIT { log.Printf("✓ Access GRANTED") if len(decisionResult.GetRequiredObligations()) > 0 { log.Printf("Required obligations: %v", decisionResult.GetRequiredObligations()) diff --git a/code_samples/authorization/get_entitlements.mdx b/code_samples/authorization/get_entitlements.mdx index 1a6ccc53..178d3974 100644 --- a/code_samples/authorization/get_entitlements.mdx +++ b/code_samples/authorization/get_entitlements.mdx @@ -13,7 +13,7 @@ import ( "context" "log" - authorizationv2 "github.com/opentdf/platform/protocol/go/authorization/v2" + authorization "github.com/opentdf/platform/protocol/go/authorization/v2" "github.com/opentdf/platform/sdk" ) @@ -32,10 +32,10 @@ func main() { } // Get Entitlements using v2 API - // Use authorizationv2.ForClientID to create an EntityIdentifier in one call. + // Use authorization.ForClientID to create an EntityIdentifier in one call. // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken - entitlementReq := &authorizationv2.GetEntitlementsRequest{ - EntityIdentifier: authorizationv2.ForClientID("opentdf"), + entitlementReq := &authorization.GetEntitlementsRequest{ + EntityIdentifier: authorization.ForClientID("opentdf"), } entitlements, err := client.AuthorizationV2.GetEntitlements(context.Background(), entitlementReq) From b8468f594d28da1f7ff2e577b950d7467aa8fa8a Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Tue, 31 Mar 2026 17:24:01 -0700 Subject: [PATCH 4/9] chore(deps): update vendored OpenAPI specs (selectors) Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- specs/policy/selectors.openapi.yaml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specs/policy/selectors.openapi.yaml b/specs/policy/selectors.openapi.yaml index e2d3c3a7..4afe988b 100644 --- a/specs/policy/selectors.openapi.yaml +++ b/specs/policy/selectors.openapi.yaml @@ -4,6 +4,13 @@ info: paths: {} components: schemas: + policy.SortDirection: + type: string + title: SortDirection + enum: + - SORT_DIRECTION_UNSPECIFIED + - SORT_DIRECTION_ASC + - SORT_DIRECTION_DESC policy.AttributeDefinitionSelector: type: object properties: From 87bccd7caff927642fd12085ceb949e8f4acda24 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Thu, 2 Apr 2026 12:06:49 -0700 Subject: [PATCH 5/9] fix(docs): update Go samples for renamed sdk.EntityIdentifier helpers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The helpers moved from the authorization/v2 proto package to the sdk package and were renamed (e.g., ForClientID → EntityIdentifierForClientID). Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- code_samples/authorization/get_decision.mdx | 7 ++++--- code_samples/authorization/get_entitlements.mdx | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/code_samples/authorization/get_decision.mdx b/code_samples/authorization/get_decision.mdx index dd602336..72c1d815 100644 --- a/code_samples/authorization/get_decision.mdx +++ b/code_samples/authorization/get_decision.mdx @@ -33,10 +33,11 @@ func main() { } // Get Decision using v2 API - // Use authorization.ForClientID to create an EntityIdentifier in one call. - // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken + // Use sdk.EntityIdentifierForClientID to create an EntityIdentifier in one call. + // Other helpers: EntityIdentifierForEmail, EntityIdentifierForUserName, + // EntityIdentifierForToken, EntityIdentifierWithRequestToken decisionReq := &authorization.GetDecisionRequest{ - EntityIdentifier: authorization.ForClientID("opentdf"), + EntityIdentifier: sdk.EntityIdentifierForClientID("opentdf"), Action: &policy.Action{ Name: "decrypt", }, diff --git a/code_samples/authorization/get_entitlements.mdx b/code_samples/authorization/get_entitlements.mdx index 178d3974..759e2d79 100644 --- a/code_samples/authorization/get_entitlements.mdx +++ b/code_samples/authorization/get_entitlements.mdx @@ -32,10 +32,11 @@ func main() { } // Get Entitlements using v2 API - // Use authorization.ForClientID to create an EntityIdentifier in one call. - // Other helpers: ForEmail, ForUserName, ForToken, WithRequestToken + // Use sdk.EntityIdentifierForClientID to create an EntityIdentifier in one call. + // Other helpers: EntityIdentifierForEmail, EntityIdentifierForUserName, + // EntityIdentifierForToken, EntityIdentifierWithRequestToken entitlementReq := &authorization.GetEntitlementsRequest{ - EntityIdentifier: authorization.ForClientID("opentdf"), + EntityIdentifier: sdk.EntityIdentifierForClientID("opentdf"), } entitlements, err := client.AuthorizationV2.GetEntitlements(context.Background(), entitlementReq) From e2cc37c915b91737d354c83a6578494326f78edd Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 6 Apr 2026 13:18:31 -0700 Subject: [PATCH 6/9] docs(sdk): update Go samples to use proto-package helpers Helpers now live in the authorizationv2 proto package instead of the sdk package: authorization.ForClientID() instead of sdk.EntityIdentifierForClientID(). Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- code_samples/authorization/get_decision.mdx | 7 +++---- code_samples/authorization/get_entitlements.mdx | 7 +++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/code_samples/authorization/get_decision.mdx b/code_samples/authorization/get_decision.mdx index 72c1d815..34328902 100644 --- a/code_samples/authorization/get_decision.mdx +++ b/code_samples/authorization/get_decision.mdx @@ -33,11 +33,10 @@ func main() { } // Get Decision using v2 API - // Use sdk.EntityIdentifierForClientID to create an EntityIdentifier in one call. - // Other helpers: EntityIdentifierForEmail, EntityIdentifierForUserName, - // EntityIdentifierForToken, EntityIdentifierWithRequestToken + // Convenience constructors live in the authorization/v2 package: + // ForClientID, ForEmail, ForUserName, ForToken, WithRequestToken decisionReq := &authorization.GetDecisionRequest{ - EntityIdentifier: sdk.EntityIdentifierForClientID("opentdf"), + EntityIdentifier: authorization.ForClientID("opentdf"), Action: &policy.Action{ Name: "decrypt", }, diff --git a/code_samples/authorization/get_entitlements.mdx b/code_samples/authorization/get_entitlements.mdx index 759e2d79..f03b9a82 100644 --- a/code_samples/authorization/get_entitlements.mdx +++ b/code_samples/authorization/get_entitlements.mdx @@ -32,11 +32,10 @@ func main() { } // Get Entitlements using v2 API - // Use sdk.EntityIdentifierForClientID to create an EntityIdentifier in one call. - // Other helpers: EntityIdentifierForEmail, EntityIdentifierForUserName, - // EntityIdentifierForToken, EntityIdentifierWithRequestToken + // Convenience constructors live in the authorization/v2 package: + // ForClientID, ForEmail, ForUserName, ForToken, WithRequestToken entitlementReq := &authorization.GetEntitlementsRequest{ - EntityIdentifier: sdk.EntityIdentifierForClientID("opentdf"), + EntityIdentifier: authorization.ForClientID("opentdf"), } entitlements, err := client.AuthorizationV2.GetEntitlements(context.Background(), entitlementReq) From f6ac2be207ddb5898a95f29974d6a6788ce9da98 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 6 Apr 2026 13:23:49 -0700 Subject: [PATCH 7/9] docs(sdk): document EntityIdentifier helpers and update V2 Go examples - Add "Entity Identifier Helpers (Go)" reference section with table of all 5 constructors and before/after example - Update all V2 Go examples to use the helpers instead of verbose proto nesting (entitlements, decision, bulk, token) - Link obligations docs from best practices section Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/sdks/authorization.mdx | 116 +++++++++++++++++------------------- 1 file changed, 54 insertions(+), 62 deletions(-) diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index a59e6848..56e129ac 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -143,35 +143,21 @@ Use `GetEntitlements` to discover what attribute values an entity can access. Th ```go func getEntitlementsV2(client *sdk.SDK) { - // Using v2 API with EntityIdentifier entitlementReq := &authorizationv2.GetEntitlementsRequest{ - EntityIdentifier: &authorizationv2.EntityIdentifier{ - Identifier: &authorizationv2.EntityIdentifier_EntityChain{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{ - { - EphemeralId: "user-bob", - EntityType: &entity.Entity_EmailAddress{ - EmailAddress: "bob@OrgA.com", - }, - }, - }, - }, - }, - }, + EntityIdentifier: authorizationv2.ForEmail("bob@OrgA.com"), } - + entitlements, err := client.AuthorizationV2.GetEntitlements( - context.Background(), + context.Background(), entitlementReq, ) if err != nil { log.Fatal(err) } - + // Process entitlements for _, entitlement := range entitlements.GetEntitlements() { - fmt.Printf("Entity has access to: %v\n", + fmt.Printf("Entity has access to: %v\n", entitlement.GetActionsPerAttributeValueFqn()) } } @@ -405,20 +391,7 @@ Use `GetDecision` when you need to authorize access to specific resources. This ```go func getDecisionV2(client *sdk.SDK) { decisionReq := &authorizationv2.GetDecisionRequest{ - EntityIdentifier: &authorizationv2.EntityIdentifier{ - Identifier: &authorizationv2.EntityIdentifier_EntityChain{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{ - { - EphemeralId: "user-123", - EntityType: &entity.Entity_EmailAddress{ - EmailAddress: "user@company.com", - }, - }, - }, - }, - }, - }, + EntityIdentifier: authorizationv2.ForEmail("user@company.com"), Action: &policy.Action{ Name: "decrypt", }, @@ -433,15 +406,15 @@ func getDecisionV2(client *sdk.SDK) { }, }, } - + decision, err := client.AuthorizationV2.GetDecision( - context.Background(), + context.Background(), decisionReq, ) if err != nil { log.Fatal(err) } - + resDecision := decision.GetDecision() if resDecision.GetDecision() == authorizationv2.Decision_DECISION_PERMIT { fmt.Println("Access granted") @@ -624,20 +597,7 @@ func getBulkDecisionsV2(client *sdk.SDK) { bulkReq := &authorizationv2.GetDecisionBulkRequest{ DecisionRequests: []*authorizationv2.GetDecisionMultiResourceRequest{ { - EntityIdentifier: &authorizationv2.EntityIdentifier{ - Identifier: &authorizationv2.EntityIdentifier_EntityChain{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{ - { - EphemeralId: "user-123", - EntityType: &entity.Entity_EmailAddress{ - EmailAddress: "user@company.com", - }, - }, - }, - }, - }, - }, + EntityIdentifier: authorizationv2.ForEmail("user@company.com"), Action: &policy.Action{Name: "decrypt"}, Resources: []*authorizationv2.Resource{ { @@ -874,11 +834,50 @@ OpenTDF supports various entity types for flexible authentication: - **ClientId**: Service-to-service authentication - **EmailAddress**: User identification via email -- **UserName**: User identification via username +- **UserName**: User identification via username - **UUID**: Direct entity UUID reference - **Token**: JWT-based authentication - **Claims**: Custom claims-based entities +### Entity Identifier Helpers (Go) + +The Go SDK provides convenience constructors in the `authorization/v2` package that eliminate the deeply nested proto construction required to build an `EntityIdentifier`. These helpers are available starting with the `protocol/go` module version that includes [opentdf/platform#3232](https://github.com/opentdf/platform/pull/3232). + +| Helper | Description | +|--------|-------------| +| `authorization.ForClientID(clientID string)` | Identifies a subject entity by client ID | +| `authorization.ForEmail(email string)` | Identifies a subject entity by email address | +| `authorization.ForUserName(username string)` | Identifies a subject entity by username | +| `authorization.ForToken(jwt string)` | Resolves the entity from the given JWT | +| `authorization.WithRequestToken()` | Derives the entity from the request's Authorization header | + +```go +import authorization "github.com/opentdf/platform/protocol/go/authorization/v2" + +// Before: 8+ lines of nested proto construction +req := &authorization.GetDecisionRequest{ + EntityIdentifier: &authorization.EntityIdentifier{ + Identifier: &authorization.EntityIdentifier_EntityChain{ + EntityChain: &entity.EntityChain{ + Entities: []*entity.Entity{{ + EntityType: &entity.Entity_ClientId{ClientId: "opentdf"}, + Category: entity.Entity_CATEGORY_SUBJECT, + }}, + }, + }, + }, + // ... +} + +// After: one line +req := &authorization.GetDecisionRequest{ + EntityIdentifier: authorization.ForClientID("opentdf"), + // ... +} +``` + +All five constructors work with every v2 authorization method: `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk`, and `GetEntitlements`. + ### Token-Based Authentication Example @@ -889,14 +888,7 @@ OpenTDF supports various entity types for flexible authentication: ```go func getDecisionWithTokenV2(client *sdk.SDK, jwtToken string) { decisionReq := &authorizationv2.GetDecisionRequest{ - EntityIdentifier: &authorizationv2.EntityIdentifier{ - Identifier: &authorizationv2.EntityIdentifier_Token{ - Token: &entity.Token{ - EphemeralId: "token-1", - Jwt: jwtToken, - }, - }, - }, + EntityIdentifier: authorizationv2.ForToken(jwtToken), Action: &policy.Action{Name: "decrypt"}, Resource: &authorizationv2.Resource{ Resource: &authorizationv2.Resource_AttributeValues_{ @@ -906,7 +898,7 @@ func getDecisionWithTokenV2(client *sdk.SDK, jwtToken string) { }, }, } - + decision, err := client.AuthorizationV2.GetDecision( context.Background(), decisionReq, @@ -914,7 +906,7 @@ func getDecisionWithTokenV2(client *sdk.SDK, jwtToken string) { if err != nil { log.Fatal(err) } - + resDecision := decision.GetDecision() fmt.Printf("Token-based decision: %v\n", resDecision.GetDecision()) } @@ -1048,7 +1040,7 @@ async function getDecisionWithToken(platformClient: PlatformClient, jwtToken: st 1. **Least Privilege**: Request only the minimum necessary permissions 2. **Token Validation**: Ensure JWT tokens are properly validated before use -3. **Obligation Handling**: Always process and fulfill returned obligations +3. **Obligation Handling**: Always process and fulfill returned [obligations](/sdks/policy#obligations) 4. **Error Handling**: Implement proper error handling and fallback policies ### Integration Patterns From 1abcca4cbca1f7565384dd2991299d38bdcb720b Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 6 Apr 2026 13:27:29 -0700 Subject: [PATCH 8/9] docs(sdk): collapse V1 API examples behind details/summary V1 API sections are now hidden by default in collapsible
blocks so the page leads with the recommended V2 API. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/sdks/authorization.mdx | 55 +++++++++++++++++++++++-------------- 1 file changed, 35 insertions(+), 20 deletions(-) diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index 56e129ac..af060573 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -163,7 +163,8 @@ func getEntitlementsV2(client *sdk.SDK) { } ``` -#### V1 API (Legacy) +
+V1 API (Legacy) ```go func getEntitlementsV1(client *sdk.SDK) { @@ -188,27 +189,29 @@ func getEntitlementsV1(client *sdk.SDK) { }, }}, }} - + decisionRequest := &authorization.GetDecisionsRequest{ DecisionRequests: decisionRequests, } - + decisionResponse, err := client.Authorization.GetDecisions( - context.Background(), + context.Background(), decisionRequest, ) if err != nil { log.Fatal(err) } - + // Process decisions to understand entitlements for _, dr := range decisionResponse.GetDecisionResponses() { - fmt.Printf("Entity chain %s has decision: %v\n", + fmt.Printf("Entity chain %s has decision: %v\n", dr.GetEntityChainId(), dr.GetDecision()) } } ``` +
+ @@ -427,7 +430,8 @@ func getDecisionV2(client *sdk.SDK) { } ``` -#### V1 API (Legacy) +
+V1 API (Legacy) ```go func getDecisionV1(client *sdk.SDK) { @@ -452,19 +456,19 @@ func getDecisionV1(client *sdk.SDK) { }, }}, }} - + decisionRequest := &authorization.GetDecisionsRequest{ DecisionRequests: decisionRequests, } - + decisionResponse, err := client.Authorization.GetDecisions( - context.Background(), + context.Background(), decisionRequest, ) if err != nil { log.Fatal(err) } - + for _, dr := range decisionResponse.GetDecisionResponses() { if dr.GetDecision() == authorization.DecisionResponse_DECISION_PERMIT { fmt.Println("Access granted") @@ -479,6 +483,8 @@ func getDecisionV1(client *sdk.SDK) { } ``` +
+ @@ -643,7 +649,8 @@ func getBulkDecisionsV2(client *sdk.SDK) { } ``` -#### V1 API (Legacy) +
+V1 API (Legacy) ```go func getBulkDecisionsV1(client *sdk.SDK) { @@ -668,11 +675,11 @@ func getBulkDecisionsV1(client *sdk.SDK) { }, }, }} - + decisionRequest := &authorization.GetDecisionsRequest{ DecisionRequests: decisionRequests, } - + decisionResponse, err := client.Authorization.GetDecisions( context.Background(), decisionRequest, @@ -680,7 +687,7 @@ func getBulkDecisionsV1(client *sdk.SDK) { if err != nil { log.Fatal(err) } - + for _, dr := range decisionResponse.GetDecisionResponses() { fmt.Printf("Entity chain %s: %v\n", dr.GetEntityChainId(), @@ -692,6 +699,8 @@ func getBulkDecisionsV1(client *sdk.SDK) { } ``` +
+ @@ -753,12 +762,15 @@ public void getBulkDecisions(SDK sdk) throws ExecutionException, InterruptedExce } ``` -#### V1 API (Legacy) +
+V1 API (Legacy) import GetDecisionsExample from '@site/code_samples/java/get-decisions.mdx'; +
+ @@ -912,7 +924,8 @@ func getDecisionWithTokenV2(client *sdk.SDK, jwtToken string) { } ``` -#### V1 API (Legacy) +
+V1 API (Legacy) ```go func getDecisionWithTokenV1(client *sdk.SDK, jwtToken string) { @@ -935,11 +948,11 @@ func getDecisionWithTokenV1(client *sdk.SDK, jwtToken string) { AttributeValueFqns: []string{"https://company.com/attr/clearance/value/public"}, }}, }} - + decisionRequest := &authorization.GetDecisionsRequest{ DecisionRequests: decisionRequests, } - + decisionResponse, err := client.Authorization.GetDecisions( context.Background(), decisionRequest, @@ -947,7 +960,7 @@ func getDecisionWithTokenV1(client *sdk.SDK, jwtToken string) { if err != nil { log.Fatal(err) } - + for _, dr := range decisionResponse.GetDecisionResponses() { fmt.Printf("Token-based decision: %v\n", dr.GetDecision()) if len(dr.GetObligations()) > 0 { @@ -957,6 +970,8 @@ func getDecisionWithTokenV1(client *sdk.SDK, jwtToken string) { } ``` +
+ From 7281338edd43d2dfb14c027e12dbb50c71b0013f Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Mon, 6 Apr 2026 13:32:55 -0700 Subject: [PATCH 9/9] docs(sdk): simplify helper section, use authorizationv2 prefix in table - Remove before/after from the helper section, just show usage - Use authorizationv2 prefix in the helper table since shown without import context - Remove PR link from helper description Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/sdks/authorization.mdx | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/docs/sdks/authorization.mdx b/docs/sdks/authorization.mdx index af060573..77580c55 100644 --- a/docs/sdks/authorization.mdx +++ b/docs/sdks/authorization.mdx @@ -853,35 +853,19 @@ OpenTDF supports various entity types for flexible authentication: ### Entity Identifier Helpers (Go) -The Go SDK provides convenience constructors in the `authorization/v2` package that eliminate the deeply nested proto construction required to build an `EntityIdentifier`. These helpers are available starting with the `protocol/go` module version that includes [opentdf/platform#3232](https://github.com/opentdf/platform/pull/3232). +The Go SDK provides convenience constructors in the `authorization/v2` package that eliminate the deeply nested proto construction required to build an `EntityIdentifier`. | Helper | Description | |--------|-------------| -| `authorization.ForClientID(clientID string)` | Identifies a subject entity by client ID | -| `authorization.ForEmail(email string)` | Identifies a subject entity by email address | -| `authorization.ForUserName(username string)` | Identifies a subject entity by username | -| `authorization.ForToken(jwt string)` | Resolves the entity from the given JWT | -| `authorization.WithRequestToken()` | Derives the entity from the request's Authorization header | +| `authorizationv2.ForClientID(clientID string)` | Identifies a subject entity by client ID | +| `authorizationv2.ForEmail(email string)` | Identifies a subject entity by email address | +| `authorizationv2.ForUserName(username string)` | Identifies a subject entity by username | +| `authorizationv2.ForToken(jwt string)` | Resolves the entity from the given JWT | +| `authorizationv2.WithRequestToken()` | Derives the entity from the request's Authorization header | ```go import authorization "github.com/opentdf/platform/protocol/go/authorization/v2" -// Before: 8+ lines of nested proto construction -req := &authorization.GetDecisionRequest{ - EntityIdentifier: &authorization.EntityIdentifier{ - Identifier: &authorization.EntityIdentifier_EntityChain{ - EntityChain: &entity.EntityChain{ - Entities: []*entity.Entity{{ - EntityType: &entity.Entity_ClientId{ClientId: "opentdf"}, - Category: entity.Entity_CATEGORY_SUBJECT, - }}, - }, - }, - }, - // ... -} - -// After: one line req := &authorization.GetDecisionRequest{ EntityIdentifier: authorization.ForClientID("opentdf"), // ...