feat(docs): add Authorization REST API integration guide#285
feat(docs): add Authorization REST API integration guide#285marythought wants to merge 2 commits intomainfrom
Conversation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
| } | ||
| ``` | ||
|
|
||
| To use a different identifier type, replace `emailAddress` with the appropriate field: |
There was a problem hiding this comment.
The instruction to "replace emailAddress with the appropriate field" is misleading for the token identifier type. While clientId and userName are fields within an Entity object (inside entityChain), token is a top-level alternative to entityChain within the EntityIdentifier object and has a different JSON structure.
To use a JWT, you must replace the entire entityChain block with a token block:
{
"entityIdentifier": {
"token": {
"ephemeralId": "token-correlation-id",
"jwt": "YOUR_JWT_HERE"
}
}
}| | `/authorization.v2.AuthorizationService/GetDecision` | v2 | Single entity + action + resource decision | | ||
| | `/authorization.v2.AuthorizationService/GetDecisionBulk` | v2 | Batch decisions for multiple entities/resources | | ||
| | `/authorization.v2.AuthorizationService/GetEntitlements` | v2 | List all attribute values an entity can access | | ||
| | `/authorization.AuthorizationService/GetDecisions` | v1 (legacy) | Batch decisions (v1 format) | |
There was a problem hiding this comment.
The v1 GetDecisions endpoint is explicitly mapped to /v1/authorization in the OpenAPI specification (specs/authorization/authorization.openapi.yaml). While the gRPC-style path might be supported by the gateway, using the versioned path is more consistent with the RESTful patterns documented in the spec.
|
❌ 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: |
|
❌ 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: |
| <TabItem value="ts" label="TypeScript (fetch)"> | ||
|
|
||
| ```typescript | ||
| async function getClientToken( |
There was a problem hiding this comment.
It's probably good to mention the permissions the token should have so virtru can use it to authenticate requests.
Additionally, i needed to put a custom audience to the token that matched the url of virtru so the token was accepted. That would be good to mention on the docs too 👀
| } | ||
| ``` | ||
|
|
||
| The `decision` field is either `DECISION_PERMIT` or `DECISION_DENY`. If `requiredObligations` is non-empty, your application must enforce those obligations (e.g., watermarking, audit logging). See [Obligations](/sdks/obligations) for details. |
There was a problem hiding this comment.
There's also (on the docs) a decision unknown type. Not sure what this meant, but it's good if we document it here too.
|
|
||
| For large-scale evaluations (e.g., re-evaluating room membership for all users), send requests in batches rather than one massive payload: | ||
|
|
||
| - **Batch size:** 100–200 decision requests per call |
There was a problem hiding this comment.
batching is also required because GetDecisionBulk supports up to 200 decisions per request.
|
|
||
| ```typescript | ||
| const response = await fetch( | ||
| `${platformUrl}/authorization.v2.AuthorizationService/GetDecisionBulk`, |
There was a problem hiding this comment.
One important note is that we have to rely on index-matching for knowing that a decision is made for an entity, since the bulk endpoint doesn't return any information regarding the entity.
Other option would be to pass the entityId on the ephemeralResourceId too, but that seems semantically incorrect.
2 participants
Summary
/guides/authorization-rest-apishowing how to call the OpenTDF Authorization Service directly over HTTP, without an SDKContext
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
/guides/authorization-rest-api/sdks/authorization,/sdks/obligations,/guides/authentication-guideresolve🤖 Generated with Claude Code