feat(docs): add Authorization REST API integration guide by marythought · Pull Request #285 · opentdf/docs

marythought · 2026-04-07T17:22:54Z

Summary

Adds a new guide at /guides/authorization-rest-api showing how to call the OpenTDF Authorization Service directly over HTTP, without an SDK
Targets server-side integrators using Node.js, Python, Ruby, or any language without an OpenTDF SDK
Covers authentication (OIDC client credentials), health checks, GetDecision, GetDecisionBulk, GetEntitlements, attribute FQN construction, entity identifiers, batching strategies, and production best practices
Follows existing guide conventions (mermaid diagrams, tabbed code examples, admonitions, production checklist)

Context

Rocket.Chat PR #39845 built a full Virtru PDP integration by hand-rolling ~200 lines of HTTP calls. The existing authorization docs cover SDK usage only — this guide fills the gap for server-side REST API consumers.

Test plan

Dev server renders the page at /guides/authorization-rest-api
Mermaid sequence diagram renders
Tab components (curl / TypeScript / Python) work
Cross-links to /sdks/authorization, /sdks/obligations, /guides/authentication-guide resolve
Page appears in the Guides sidebar section

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request introduces a comprehensive guide for the Authorization REST API, covering authentication, health checks, and core service endpoints with examples in multiple languages. The review feedback identifies a technical inaccuracy regarding the JSON structure for JWT-based entity identifiers and suggests using versioned REST paths for legacy v1 endpoints to maintain consistency with the OpenAPI specification.

github-actions · 2026-04-07T17:27:06Z

❌ 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-285.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"

github-actions · 2026-04-07T17:38:18Z

❌ 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-285.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"

KevLehman

Great docs!

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

- Fix token entity identifier structure (top-level alternative to entityChain, not a field within it) - Use versioned REST path /v1/authorization for legacy GetDecisions endpoint - Add audience configuration warning for OIDC tokens - Document DECISION_UNSPECIFIED alongside PERMIT and DENY - Note 200-request hard limit on GetDecisionBulk - Document index-matched bulk responses with no entity info - Update vendored OpenAPI specs (authorization, kasregistry) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

… fence Wrap GetDecision, GetDecisionBulk, and GetEntitlements tab examples in <details>/<summary> blocks so the page is easier to scan. Also wrap the batching strategy TypeScript snippet and remove a stray ``` after the index-matching caution admonition. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Link each endpoint section and the endpoint reference table to the corresponding auto-generated OpenAPI schema pages under /OpenAPI-clients/authorization/v2/. Also add a top-level link to the OpenAPI reference in the intro paragraph. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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

coderabbitai · 2026-04-24T18:27:09Z

Warning

Rate limit exceeded

@marythought has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 59 minutes and 28 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9d56931f-6144-40a4-a441-e6eb1394ca3a

📥 Commits

Reviewing files that changed from the base of the PR and between a82f860 and 864728d.

📒 Files selected for processing (1)

docs/guides/authorization-rest-api.mdx

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch worktree-DSPX-2802-rest-api-guide

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.}

jakedoublev

These enhancements are really great. I have a couple pieces of feedback before we merge.

Replace incorrect gRPC-Gateway reference with ConnectRPC (HTTP/1.1 and HTTP/2 supported natively, no gateway needed). Add JWT validation warning for integrator PEPs passing tokens to the authorization service. Also includes previously staged v1-to-v2 migration details section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gemini-code-assist Bot reviewed Apr 7, 2026

View reviewed changes

Comment thread docs/guides/authorization-rest-api.mdx Outdated

Comment thread docs/guides/authorization-rest-api.mdx Outdated

KevLehman reviewed Apr 14, 2026

View reviewed changes

Comment thread docs/guides/authorization-rest-api.mdx

Comment thread docs/guides/authorization-rest-api.mdx Outdated

Comment thread docs/guides/authorization-rest-api.mdx Outdated

Comment thread docs/guides/authorization-rest-api.mdx

opentdf deleted a comment from coderabbitai Bot Apr 24, 2026

marythought and others added 6 commits April 24, 2026 11:25

feat(docs): add Authorization REST API integration guide

d781b22

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

fix(docs): fix broken best-practices anchor link in health check section

bed273d

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

fix(docs): add cross-links, curl batching example, and FQN naming rul…

ed01b18

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

marythought force-pushed the worktree-DSPX-2802-rest-api-guide branch from 23ba3a4 to ed01b18 Compare April 24, 2026 18:27

marythought marked this pull request as ready for review April 24, 2026 18:27

marythought requested review from a team as code owners April 24, 2026 18:27

KevLehman approved these changes Apr 24, 2026

View reviewed changes

jakedoublev reviewed Apr 27, 2026

View reviewed changes

Comment thread docs/guides/authorization-rest-api.mdx Outdated

Comment thread docs/guides/authorization-rest-api.mdx

jakedoublev approved these changes Apr 27, 2026

View reviewed changes

marythought merged commit 5eeb113 into main Apr 27, 2026
8 checks passed

marythought deleted the worktree-DSPX-2802-rest-api-guide branch April 27, 2026 18:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): add Authorization REST API integration guide#285

feat(docs): add Authorization REST API integration guide#285
marythought merged 7 commits intomainfrom
worktree-DSPX-2802-rest-api-guide

marythought commented Apr 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

KevLehman left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai Bot commented Apr 24, 2026 •

edited

Loading

Rate limit exceeded

Uh oh!

jakedoublev left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

marythought commented Apr 7, 2026

Summary

Context

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

KevLehman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Rate limit exceeded

Uh oh!

jakedoublev 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!

3 participants

coderabbitai Bot commented Apr 24, 2026 •

edited

Loading