chore(docs): restructure Authorization page by marythought · Pull Request #282 · opentdf/docs

marythought · 2026-04-07T16:32:47Z

Summary

Restructure the Authorization SDK page to match the pattern used on TDF and Policy pages.
preview: https://opentdf-docs-pr-282.surge.sh/sdks/authorization

Rename sections to method names: GetEntitlements, GetDecision, GetDecisionBulk
Add Setup section with stripped-down client init
Add EntityIdentifier type reference with Go helpers + Java/JS equivalents table
Add Signature → Parameters → Example → Returns to each method
Add Type Reference section: Decision, ResourceDecision, Resource, EntityEntitlements, GetDecisionMultiResourceResponse
Update Entitlements with Scope to use v2 API (was incorrectly documented as v1-only)
Add Go imports to each code example
V1 legacy examples tucked into collapsible blocks

Content comparison with main

Main section	Branch equivalent	Status
Overview (Entitlements vs Decisions, Typical Workflow)	Condensed into intro paragraph	Covered
Authentication Setup (full boilerplate)	Setup (stripped down)	Improved
Getting Entitlements / Basic Query	GetEntitlements with Signature/Params/Returns	Improved
Entitlements with Scope	Merged as second example under GetEntitlements	Covered
Single Resource Decision	GetDecision	Improved
Bulk Authorization Decisions	GetDecisionBulk	Improved
Supported Entity Types (bullet list)	Entity types table in EntityIdentifier section	Covered (incl. Claims)
Entity Identifier Helpers (Go)	EntityIdentifier section with all 3 languages	Improved
Token-Based Authentication Example	Merged as second example under GetDecision	Covered
Best Practices	Best Practices (condensed)	Covered
Error Handling	Error Handling	Covered
(not in main)	Type Reference section	New

Part of #274

Test plan

Verify method-name headings render correctly
Verify EntityIdentifier docs with cross-language table
Verify type reference links resolve
Verify v2 entitlements with scope example

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Reworked Authorization guide into entitlements vs per-resource decision model and added batch evaluation guidance.
- Added GetDecisionBulk docs and recommended bulk usage for performance; clarified when to use comprehensive hierarchy.
- Added EntityIdentifier section with per-language construction examples and supported types.
- Standardized API signatures, return semantics, type references, and updated best practices emphasizing obligations handling and deny-by-default error behavior.

- Rename sections to method names: GetEntitlements, GetDecision, GetDecisionBulk - Add Setup section, EntityIdentifier type reference with cross-language table - Add Signature/Parameters/Returns to each method - Add Type Reference: Decision, ResourceDecision, Resource, EntityEntitlements, GetDecisionMultiResourceResponse - Update Entitlements with Scope to use v2 API - Add Go imports to each code example - V1 legacy examples in collapsible blocks Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-04-07T16:32:55Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e5c65f1a-ee09-48c7-b040-cd5964e20ca7

📥 Commits

Reviewing files that changed from the base of the PR and between 46c8a45 and 6dc7ecc.

📒 Files selected for processing (1)

docs/sdks/authorization.mdx

📝 Walkthrough

Walkthrough

The authorization SDK docs were restructured: the page was reframed to an "Authorization" overview, added EntityIdentifier guidance, standardized GetEntitlements/GetDecision signatures, introduced GetDecisionBulk for batch evaluation, expanded type references, and updated best practices and error-handling to prefer bulk evaluation and deny-by-default behavior.

Changes

Cohort / File(s)	Summary
Authorization SDK Documentation `docs/sdks/authorization.mdx`	Rewrote and reorganized the page: replaced full SDK construction examples with snippets assuming an existing client; added an EntityIdentifier section with per-language construction patterns; standardized API docs and examples for `GetEntitlements`, `GetDecision`, and added `GetDecisionBulk` (batch model with `ephemeralId` correlation); expanded Type Reference entries (Decision, ResourceDecision, Resource, EntityEntitlements, GetDecisionMultiResourceResponse); updated best practices and error-handling to favor `GetDecisionBulk`, limit comprehensive hierarchy use, handle obligations, and implement deny-by-default on errors.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related PRs

docs(sdk): update Go authorization samples to use EntityIdentifier helpers #269: Modifies the same authorization SDK docs and Go v2 examples to replace manual EntityIdentifier proto construction with helper constructors.

Suggested reviewers

elizabethhealy
jp-ayyappan
eugenioenko

Poem

🐰 I hopped through docs to tidy the trail,
Entities, bulk calls — a streamlined tale.
GetDecisionBulk hops fast in a line,
Correlate ephemeral IDs, everything's fine.
Deny by default keeps the burrow divine.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore(docs): restructure Authorization page' accurately reflects the main change—restructuring the Authorization SDK documentation—which is confirmed by the PR objectives and the detailed summary of changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch chore/274-d-authorization-restructure

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist

Code Review

This pull request refactors the SDK authorization documentation, streamlining setup examples and providing detailed guides for EntityIdentifier, GetEntitlements, GetDecision, and GetDecisionBulk across Go, Java, and JavaScript. It also adds best practices and a type reference section. Review feedback identifies inconsistencies in the JavaScript EntityIdentifier snippet, questions the inclusion of a UUID entity type not found in the schema, and suggests improving Go code examples by avoiding the direct printing of pointer slices.

github-actions · 2026-04-07T16:36:54Z

❌ Surge preview build failed — no preview was deployed. Check the workflow logs for details.

Once the build passes, the preview will be at: https://opentdf-docs-pr-282.surge.sh

Common cause: If the build failed on vendored YAML validation, run the following locally and commit the result:

npm run update-vendored-yaml
git add specs/
git commit -m "chore(deps): update vendored OpenAPI specs"

- Remove UUID from entity types table — not available in v2 API - Replace log.Printf with iteration in scoped entitlements example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Claims was listed in the original docs but dropped during restructure. It's a valid v2 entity type used by the Entity Resolution Service. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Restore the workflow guidance from main (resource discovery → resource access → bulk operations) as a section near the bottom, matching the pattern used on the Discovery page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…types Available as both an entity identifier (resource acts as entity for authorization) and a resource variant (alternative to attribute value FQNs). Links to registered resources concept page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-07T17:37:16Z

❌ Surge preview build failed — no preview was deployed. Check the workflow logs for details.

Once the build passes, the preview will be at: https://opentdf-docs-pr-282.surge.sh

Common cause: If the build failed on vendored YAML validation, run the following locally and commit the result:

npm run update-vendored-yaml
git add specs/
git commit -m "chore(deps): update vendored OpenAPI specs"

The /sdks/obligations page is created in a separate PR. Link to the existing concept page to avoid broken link in CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Type Reference → Typical Workflow → Best Practices → Error Handling Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/sdks/authorization.mdx`:
- Line 70: Update the documentation sentence that lists allowed forms of an
EntityIdentifier by removing "UUID" so it matches the v2 supported-entity-types
section and PR intent; locate the line referencing EntityIdentifier in
docs/sdks/authorization.mdx (the sentence starting "Every authorization call
requires an `EntityIdentifier`") and edit the list of identifier types to
exclude UUID while keeping email, username, client ID, and JWT token.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5fa2d073-a6fb-494f-bc3e-2ed98a263b6e

📥 Commits

Reviewing files that changed from the base of the PR and between d999665 and 46c8a45.

📒 Files selected for processing (1)

docs/sdks/authorization.mdx

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

marythought requested review from a team as code owners April 7, 2026 16:32

gemini-code-assistBot reviewed Apr 7, 2026
View reviewed changes

Comment threaddocs/sdks/authorization.mdx
Comment threaddocs/sdks/authorization.mdx Outdated
Comment threaddocs/sdks/authorization.mdx Outdated

marythoughtand others added 3 commits April 7, 2026 10:18

Merge branch 'main' into chore/274-d-authorization-restructure
f7431a6

fix: remove UUID entity type (v2 only), fix %v on pointer slice
0c90105
- Remove UUID from entity types table — not available in v2 API - Replace log.Printf with iteration in scoped entitlements example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: add Claims entity type back to EntityIdentifier table
5aa834c
Claims was listed in the original docs but dropped during restructure. It's a valid v2 entity type used by the Entity Resolution Service. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

opentdf deleted a comment from github-actionsBotApr 7, 2026

marythoughtand others added 2 commits April 7, 2026 10:30

opentdf deleted a comment from github-actionsBotApr 7, 2026

marythoughtand others added 2 commits April 7, 2026 10:39

fix: link obligations to concept page instead of SDK page
2173137
The /sdks/obligations page is created in a separate PR. Link to the existing concept page to avoid broken link in CI. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore(docs): reorder Authorization sections
46c8a45
Type Reference → Typical Workflow → Best Practices → Error Handling Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

coderabbitaiBot reviewed Apr 7, 2026
View reviewed changes

Comment threaddocs/sdks/authorization.mdx Outdated

elizabethhealy reviewed Apr 7, 2026
View reviewed changes

Comment threaddocs/sdks/authorization.mdx

elizabethhealy previously approved these changes Apr 7, 2026
View reviewed changes

marythoughtand others added 2 commits April 7, 2026 15:54

Merge branch 'main' into chore/274-d-authorization-restructure
7dfbd86

fix: remove UUID from EntityIdentifier description text
6dc7ecc
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

marythought dismissed elizabethhealy’s stale review via 6dc7eccApril 8, 2026 14:30

marythought requested a review from elizabethhealy April 8, 2026 14:44

elizabethhealy approved these changes Apr 8, 2026
View reviewed changes

marythought merged commit 9ddc1a5 into mainApr 8, 2026
9 checks passed

marythought deleted the chore/274-d-authorization-restructure branch April 8, 2026 16:54

coderabbitaiBot mentioned this pull request Apr 8, 2026
chore(docs): add Setup section to Authentication page #284
Merged
2 tasks

coderabbitaiBot mentioned this pull request Apr 20, 2026
chore(docs): update Java/JS examples to use EntityIdentifier helpers #291
Merged
2 tasks

This was referenced Apr 21, 2026
chore(docs): add Resource constructor helpers and update examples #301
Merged
feat(docs): add SDK version annotations & normalize setup sections #303
Merged

coderabbitaiBot mentioned this pull request Apr 29, 2026
feat(docs): document SDK.IsHealthy and link unresolved type references #311
Merged
4 tasks

Navigation Menu

Uh oh!

chore(docs): restructure Authorization page - #282

chore(docs): restructure Authorization page#282
marythought merged 10 commits into
mainfrom
chore/274-d-authorization-restructure

marythought commented Apr 7, 2026•
edited by coderabbitai Bot
Loading

Uh oh!

coderabbitaiBot commented Apr 7, 2026•
edited
Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

gemini-code-assistBot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Apr 7, 2026

Uh oh!

github-actionsBot commented Apr 7, 2026

Uh oh!

coderabbitaiBot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

marythought commented Apr 7, 2026• edited by coderabbitai BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Content comparison with main

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitaiBot commented Apr 7, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

gemini-code-assistBot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Apr 7, 2026

Uh oh!

github-actionsBot commented Apr 7, 2026

Uh oh!

coderabbitaiBot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marythought commented Apr 7, 2026•
edited by coderabbitai Bot
Loading

coderabbitaiBot commented Apr 7, 2026•
edited
Loading