Open
Conversation
Contributor
WalkthroughThe documentation for task-based authorization in OpenFGA was updated to rephrase permission terminology, convert the expiration model from turn-count to call-count semantics, rename the agent relation from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refines the Task-Based Authorization (TBAC) documentation for agents by improving wording, clarifying modeling patterns, and updating the conditions example from “turn count” to “tool call count”.
Changes:
- Reworded introductory and domain-modeling guidance to better frame TBAC and task principals.
- Updated the conditions example to use a
max_call_countcondition and related terminology (“call count”). - Expanded/adjusted later sections (agent binding naming, new tuple cleanup guidance, and an added further-reading resource).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Here we enrich an existing user-oriented model by adding `task` as a principal. Granting a `task` the `write` relation on a project gives it permission to read/edit the project and all its tickets. You can also grant permissions at the ticket level for more granular control. This makes your application ready for agent authorization with minimal changes to your existing model. | ||
| This enriches an existing user-oriented model by adding `task` as a principal. Granting a `task` the `write` relation on a project gives it permission to read and edit the project and all its tickets. You can also grant permissions at the ticket level for more granular control. This makes your application ready for agent authorization with minimal changes to your existing model. | ||
|
|
||
| If you follow this approach, your application needs to perform both user and task authorization. This means two separate checks: one to verify the user has access to a resource, and another to verify the task has permission to perform the action on behalf of the agent, as described in [Binding agents to tasks](#binding-agents-to-tasks). |
There was a problem hiding this comment.
The link to “Binding agents to tasks” doesn’t currently describe the “two separate checks” (user authorization vs task authorization). Consider either expanding that section to cover the dual-check flow, or updating this sentence to link to a section that actually explains those checks (or remove the cross-reference).
Suggested change
| If you follow this approach, your application needs to perform both user and task authorization. This means two separate checks: one to verify the user has access to a resource, and another to verify the task has permission to perform the action on behalf of the agent, as described in [Binding agents to tasks](#binding-agents-to-tasks). | |
| If you follow this approach, your application needs to perform both user and task authorization. This means two separate checks: first verify that the user has access to the resource, then verify that the task has permission to perform the requested action on the agent's behalf. |
| ``` | ||
|
|
||
| The `expiration` condition grants access for a fixed duration from the grant time. The `turn_count` condition grants access for a fixed number of agent turns. When writing the tuple, you provide the condition parameters: | ||
| The `expiration` condition grants access for a fixed duration from the grant time. The `max_call_count` condition limits how many times the tool can be called. When writing the tuple, you provide the condition parameters: |
There was a problem hiding this comment.
The semantics for current_tool_count are ambiguous (e.g., “calls already made” vs “1-based current call index”), which can lead to an off-by-one interpretation with current_tool_count < max_tool_calls. Consider clarifying in the surrounding text what value the caller should supply and when it should be incremented.
Suggested change
| The `expiration` condition grants access for a fixed duration from the grant time. The `max_call_count` condition limits how many times the tool can be called. When writing the tuple, you provide the condition parameters: | |
| The `expiration` condition grants access for a fixed duration from the grant time. The `max_call_count` condition limits how many times the tool can be called. In `max_call_count`, `current_tool_count` means the number of successful calls already made before the current authorization check. For example, pass `current_tool_count: 0` for the first call attempt, `1` for the second, and increment it only after a successful call. When writing the tuple, you provide the static condition parameters such as `grant_time`, `grant_duration`, and `max_tool_calls`; dynamic values such as `current_time` and `current_tool_count` are supplied in the check context: |
Contributor
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/modeling/agents/task-based-authorization.mdx (1)
187-210:⚠️ Potential issue | 🟡 MinorClarify call-count boundary semantics to avoid off-by-one integrations.
current_tool_count < max_tool_callsis correct, but the docs should explicitly state whethercurrent_tool_countis evaluated before the attempted call (recommended) and show one concrete check-context example. Without that, implementers can enforce one extra or one fewer call.✍️ Suggested doc tweak
-The `expiration` condition grants access for a fixed duration from the grant time. The `max_call_count` condition limits how many times the tool can be called. When writing the tuple, you provide the condition parameters: +The `expiration` condition grants access for a fixed duration from the grant time. +The `max_call_count` condition limits how many times the tool can be called. +Evaluate `current_tool_count` **before** the attempted call (0-based). +When writing the tuple, you provide the condition parameters: @@ -When checking access, pass the current time or current call count in the request context. +When checking access, pass the current time or current call count in the request context. +Example for call count: `{"current_tool_count": 1}` with `max_tool_calls: 2` still allows the second call.Also applies to: 224-234
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/content/modeling/agents/task-based-authorization.mdx` around lines 187 - 210, Update the docs around the max_call_count condition to clarify boundary semantics: explicitly state that current_tool_count is evaluated before the attempted call (so the condition current_tool_count < max_tool_calls allows another call when the current count is strictly less than the limit), and add a concrete example showing values before and after a call (e.g., max_tool_calls=3, current_tool_count=2 permits the call; after the call current_tool_count becomes 3 and subsequent calls are denied). Reference the condition name max_call_count and the parameters max_tool_calls and current_tool_count so readers can find and update the explanation and add the single concrete check-context example in the same section.
🧹 Nitpick comments (1)
docs/content/modeling/agents/task-based-authorization.mdx (1)
319-319: Split the first “Further reading” bullet for scanability.This line is dense with three resources in one bullet; splitting into a primary link plus sub-links will improve readability.
✍️ Suggested formatting
-- [From Scopes To Intent: Reimagining Authorization for Autonomous Agents](https://mcpdevsummitna26.sched.com/event/2Hbg0/from-scopes-to-intent-reimagining-authorization-for-autonomous-agents-andres-aguiar-abhishek-hingnikar-okta), MCP Dev Summit NY 2026 [code repository](https://github.com/aaguiarz/ibac-talk-demo) and [demo](https://www.youtube.com/watch?v=IVIvtusd7LA) +- [From Scopes To Intent: Reimagining Authorization for Autonomous Agents](https://mcpdevsummitna26.sched.com/event/2Hbg0/from-scopes-to-intent-reimagining-authorization-for-autonomous-agents-andres-aguiar-abhishek-hingnikar-okta) — MCP Dev Summit NY 2026 + - [Code repository](https://github.com/aaguiarz/ibac-talk-demo) + - [Demo](https://www.youtube.com/watch?v=IVIvtusd7LA)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/content/modeling/agents/task-based-authorization.mdx` at line 319, Replace the single dense "Further reading" bullet that contains the "From Scopes To Intent: Reimagining Authorization for Autonomous Agents" entry with a primary bullet linking to the talk (use the existing title link as the main item) and two nested sub-bullets that separately link to the code repository and the demo/video; locate the line containing the full combined entry ("From Scopes To Intent: Reimagining Authorization for Autonomous Agents...") and split it into one top-level bullet for the talk and two indented bullets for "[code repository](https://github.com/aaguiarz/ibac-talk-demo)" and "[demo](https://www.youtube.com/watch?v=IVIvtusd7LA)" to improve scanability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs/content/modeling/agents/task-based-authorization.mdx`:
- Around line 187-210: Update the docs around the max_call_count condition to
clarify boundary semantics: explicitly state that current_tool_count is
evaluated before the attempted call (so the condition current_tool_count <
max_tool_calls allows another call when the current count is strictly less than
the limit), and add a concrete example showing values before and after a call
(e.g., max_tool_calls=3, current_tool_count=2 permits the call; after the call
current_tool_count becomes 3 and subsequent calls are denied). Reference the
condition name max_call_count and the parameters max_tool_calls and
current_tool_count so readers can find and update the explanation and add the
single concrete check-context example in the same section.
---
Nitpick comments:
In `@docs/content/modeling/agents/task-based-authorization.mdx`:
- Line 319: Replace the single dense "Further reading" bullet that contains the
"From Scopes To Intent: Reimagining Authorization for Autonomous Agents" entry
with a primary bullet linking to the talk (use the existing title link as the
main item) and two nested sub-bullets that separately link to the code
repository and the demo/video; locate the line containing the full combined
entry ("From Scopes To Intent: Reimagining Authorization for Autonomous
Agents...") and split it into one top-level bullet for the talk and two indented
bullets for "[code repository](https://github.com/aaguiarz/ibac-talk-demo)" and
"[demo](https://www.youtube.com/watch?v=IVIvtusd7LA)" to improve scanability.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 20a64444-7f97-49eb-ac48-4f5599cc46e5
📒 Files selected for processing (1)
docs/content/modeling/agents/task-based-authorization.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
What problem is being solved?
How is it being solved?
What changes are made to solve it?
References
Review Checklist
mainSummary by CodeRabbit
Release Notes