Skip to main content

Modeling Task-Based Authorization for Agents

Agents need credentials to interact with APIs. These can be user or service credentials, for internal or third-party systems. In most cases, those permissions grant agents broad access to the system, as the authorization services that issue credentials for those APIs do not support granting fine-grained permissions. Consent prompts and service credentials are too coarse.

Task-Based Authorization grants agents access to perform specific actions only when necessary, without permanent permissions. Agents start with zero permissions and receive only what a given task requires. For example, rather than allowing an agent to create tickets across all projects, you authorize it to "Create a ticket on project X" — scoping permissions to a specific context.

This guide shows how to model task-based authorization in OpenFGA, progressing from a basic tool-calling model to patterns that support permission hierarchies, session scoping, expiration, and agent binding.

Tool authorization​

The simplest model represents tool authorization for a Model Context Protocol server. When a task starts, you write tuples granting it permission to call the tools it needs.

model
  schema 1.1

type task

type tool
  relations
    define can_call: [task, task:*]

type tool_resource
  relations
    define tool: [tool]
    define can_call: [task] or can_call from tool

A tool represents a capability (e.g. slack_send_message), and a tool_resource represents a specific target within that tool (e.g. a Slack channel). Granting can_call on a tool automatically grants access to all its resources. You can also grant access to individual resources, or use task:* to allow any task to call a tool.

For example, you can grant task:1 access to send any Slack message, while restricting task:2 to a specific channel:

tuples:
  # Any task can list Slack channels
  - user: task:*
    relation: can_call
    object: tool:slack_list_channels

  # task:1 can send any Slack message
  - user: task:1
    relation: can_call
    object: tool:slack_send_message

  # task:2 can only send messages to channel XGA14FG
  - user: task:2
    relation: can_call
    object: tool_resource:slack_send_message/XGA14FG

When checking whether task:2 can call tool_resource:slack_send_message/XGA14FG, send a contextual tuple linking the resource to its tool. This avoids storing a tuple for every channel — you provide the tool-to-resource relationship at query time.


// Run a check
const { allowed } = await fgaClient.check({
    user: 'task:2',
    relation: 'can_call',
    object: 'tool_resource:slack_send_message/XGA14FG',
    contextualTuples: [
      {"_description":"Link the tool_resource to its parent tool","user":"tool:slack_send_message","relation":"tool","object":"tool_resource:slack_send_message/XGA14FG"}
    ],
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

Domain-specific models​

The model above is generic. If you are building agents for your own application, the authorization model should reflect your application's domain. Consider a project management system:

model
  schema 1.1

type user

type task

type organization
  relations
    define admin: [user]
    define member: [user]

type project
  relations
    define organization: [organization]
    
    # relations for users
    define owner: [user]
    define member: [user]
    
    # relations for tasks
    define read: [task]
    define write: [task]
    define delete: [task]

    # permissions for users
    define can_delete: delete or owner or admin from organization
    define can_edit: write or owner or admin from organization
    define can_read: read or can_edit or member from organization
    define can_create_ticket: can_edit

type ticket
  relations
    define project: [project]
    define owner: [user]

    # relations for tasks
    define read: [task]
    define write: [task]
    define delete: [task]
    define can_delete: owner or delete or can_delete from project
    define can_edit: owner or write or can_edit from project
    define can_read: read or write or can_read from project

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.

Scoping permissions to sessions and agents​

In interactive agents, users may create multiple sessions. You can scope permissions to a session so that granting access applies to all tasks within it. You can also scope permissions to an agent, so they persist across sessions.

model
  schema 1.1

type task

type agent
  relations
    define task: [task]

type session
  relations
    define task: [task]

type tool
  relations
    define can_call: [task, session#task, agent#task]

The can_call relation accepts three types of assignments:

  • task — grant permission to a specific task.
  • session#task — grant permission to all tasks in a session. When the user says "allow this for this session", write a tuple like user: session:1#task, relation: can_call, object: tool:slack_send_message.
  • agent#task — grant permission to all tasks for an agent, across sessions. When the user says "always allow this", write a tuple with agent:1#task instead.

Each task is linked to its session and agent when created:

tuples:
  # Link task to its agent and session
  - user: task:1
    relation: task
    object: agent:1
  - user: task:1
    relation: task
    object: session:1

  # Grant session-level access
  - user: session:1#task
    relation: can_call
    object: tool:slack_send_message

Expiration and turn count​

You can use OpenFGA conditions to make permissions expire after a duration or a number of agent turns.

model
  schema 1.1

type task

type tool
  relations
    define can_call: [task, task with expiration, task with turn_count]

condition expiration(grant_time: timestamp, grant_duration: duration, current_time: timestamp) {
  current_time < grant_time + grant_duration
}

condition turn_count(turns_granted: int, current_turn: int) {
  current_turn <= turns_granted
}

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:

tuples:
  # task:1 can call the tool for 10 minutes
  - user: task:1
    relation: can_call
    object: tool:slack_send_message
    condition:
      name: expiration
      context:
        grant_time: "2026-03-22T00:00:00Z"
        grant_duration: 10m

  # task:2 can call the tool for 2 turns
  - user: task:2
    relation: can_call
    object: tool:slack_send_message
    condition:
      name: turn_count
      context:
        turns_granted: 2

When checking access, pass the current time or turn number in the request context.

Binding agents to tasks​

The examples above don't verify that the agent making the call is actually assigned to the task. You can enforce this using contextual tuples and an intersection (and) in the model, similar to the Authorization Through Organization Context pattern.

model
  schema 1.1

type task

type agent
  relations
    define task: [task]

type tool
  relations
    define agent_in_context: [agent]
    define can_call: [task] and task from agent_in_context

The can_call relation requires both that the task has been granted access and that the agent making the call is linked to the task. When the task is created, link it to its agent:

tuples:
  - user: task:1
    relation: task
    object: agent:1
  - user: task:1
    relation: can_call
    object: tool:slack_send_message

At check time, send a contextual tuple identifying the calling agent. If the agent is linked to the task, the check returns true:


// Run a check
const { allowed } = await fgaClient.check({
    user: 'task:1',
    relation: 'can_call',
    object: 'tool:slack_send_message',
    contextualTuples: [
      {"_description":"The agent making the call","user":"agent:1","relation":"agent_in_context","object":"tool:slack_send_message"}
    ],
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = true

If a different agent tries to use task:1, the check returns false because the agent-to-task link won't match:


// Run a check
const { allowed } = await fgaClient.check({
    user: 'task:1',
    relation: 'can_call',
    object: 'tool:slack_send_message',
    contextualTuples: [
      {"_description":"A different agent making the call","user":"agent:2","relation":"agent_in_context","object":"tool:slack_send_message"}
    ],
  }, {
    authorizationModelId: '01HVMMBCMGZNT3SED4Z17ECXCA',
});

// allowed = false

Delegating task permissions to sub-agents​

Sub-agents also start with zero permissions. When delegating work, you have two options:

  • Share the task: assign the same task to the sub-agent, giving it all the task's permissions.
  • Restrict further: create a new task with a narrower set of permissions for the sub-agent.

Further reading​

Mapping user intent to the right set of permissions is an active area of research. These resources explore the topic:

Take a look at the following sections for more information.
Conditions

Learn how to model relationships with conditions such as expiration and turn count

Contextual Tuples

Learn how to use contextual tuples to send dynamic context at query time