Agent Permissions

MITRITY's agent permission system controls which tools each agent can access and how. While policies govern what actions are allowed or denied, agent permissions define the boundary — which tools an agent is authorized to use at all. Permissions operate as a pre-filter: if an agent does not have permission to use a tool, the action is denied before policy evaluation.

Overview

Agent permissions link three concepts:

Agent — The AI agent performing actions
Tool — The tool from the tool catalog being accessed
Permission — The rules governing that agent's access to that tool

Each permission specifies:

Mode: Allow or deny access to the tool
Operations: Which operations are permitted (read, write, delete, etc.)
Rate limits: Maximum actions per time window
Payload limits: Maximum request size in bytes
Time windows: When the permission is active
Scopes: Fine-grained resource access within the tool

Permission Modes

Allow Mode

The agent is permitted to use the tool, subject to the configured operations, rate limits, and constraints.

{
  "agent_id": "agt_sales-bot",
  "tool_id": "tool_crm_8k2m",
  "mode": "allow",
  "operations": ["read", "list"]
}

Deny Mode

The agent is explicitly denied access to the tool. Deny permissions take precedence over allow permissions.

{
  "agent_id": "agt_sales-bot",
  "tool_id": "tool_shell_builtin",
  "mode": "deny"
}

Default Behavior

If no permission exists for an agent-tool pair, the default behavior depends on your tenant configuration:

Default Mode	Behavior
`default_deny` (recommended)	Tools without explicit permissions are denied. Agents can only use tools explicitly granted.
`default_allow`	Tools without explicit permissions are allowed. Only explicitly denied tools are blocked.

Configure the default mode in Settings > Security > Default Permission Mode.

Operations

Operations define what the agent can do with the tool. Available operations depend on the tool definition in the catalog.

Operation	Description
`read`	Retrieve data (SELECT, GET, download)
`write`	Create or update data (INSERT, UPDATE, PUT, POST, upload)
`delete`	Remove data (DELETE, DROP, remove)
`list`	Enumerate resources (list tables, list buckets, directory listing)
`execute`	Run code or invoke functions (stored procedures, lambdas, code execution)
`send`	Send messages or notifications (email, chat, SMS)

Operation Filtering

Grant only the operations the agent needs:

{
  "agent_id": "agt_analytics-bot",
  "tool_id": "tool_postgres_builtin",
  "mode": "allow",
  "operations": ["read", "list"]
}

This grants the analytics bot read-only access to PostgreSQL. Any write, delete, or execute operations will be denied.

Rate Limits

Rate limits restrict how frequently an agent can use a tool. This prevents runaway agents from overwhelming resources and provides a safety net against infinite loops.

{
  "agent_id": "agt_sales-bot",
  "tool_id": "tool_crm_8k2m",
  "mode": "allow",
  "operations": ["read", "write", "list"],
  "rate_limit": {
    "max_per_minute": 60,
    "burst": 10
  }
}

Rate Limit Fields

Field	Type	Description
`max_per_minute`	integer	Maximum number of actions per minute. Range: 1-10000.
`burst`	integer	Maximum number of concurrent actions. When exceeded, new actions are queued or denied. Range: 1-1000.

When the rate limit is exceeded, the gateway returns a 429 Too Many Requests error to the agent with a Retry-After header.

Rate Limit Recommendations

Tool Category	Recommended Rate	Burst
Database	100-500/min	20
LLM	30-60/min	5
Email/SMS	10-30/min	3
Code execution	10-20/min	2
Storage	100-300/min	20
HTTP outbound	60-200/min	10

Payload Limits

Payload limits restrict the size of data an agent can send in a single request. This prevents agents from exfiltrating large datasets or overwhelming downstream services.

{
  "agent_id": "agt_data-bot",
  "tool_id": "tool_s3_builtin",
  "mode": "allow",
  "operations": ["read", "write"],
  "max_payload_bytes": 10485760
}

Field	Type	Description
`max_payload_bytes`	integer	Maximum request body size in bytes. Default: no limit.

Common sizes:

Size	Bytes	Use Case
1 KB	1024	Simple API calls, JSON payloads
1 MB	1048576	Standard file uploads, data exports
10 MB	10485760	Large file operations
100 MB	104857600	Bulk data transfers

Time Windows

Time windows restrict tool access to specific hours. Actions outside the time window are denied.

{
  "agent_id": "agt_batch-processor",
  "tool_id": "tool_postgres_builtin",
  "mode": "allow",
  "operations": ["read", "write", "execute"],
  "time_window": {
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start": "02:00",
    "end": "06:00",
    "timezone": "Europe/Stockholm"
  }
}

Time Window Fields

Field	Type	Description
`days`	array	Days of the week the window is active. Values: `monday` through `sunday`.
`start`	string	Start time in 24-hour format (HH:MM).
`end`	string	End time in 24-hour format (HH:MM).
`timezone`	string	IANA timezone (e.g., `Europe/Stockholm`, `America/New_York`, `UTC`).

Spanning Midnight

To create a window that spans midnight (e.g., 22:00 to 06:00), set the end time before the start time:

{
  "time_window": {
    "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "start": "22:00",
    "end": "06:00",
    "timezone": "Europe/Stockholm"
  }
}

Scopes

Scopes provide fine-grained resource access within a tool. Instead of granting access to all resources within a tool, scopes limit access to specific tables, buckets, paths, or endpoints.

{
  "agent_id": "agt_analytics-bot",
  "tool_id": "tool_postgres_builtin",
  "mode": "allow",
  "operations": ["read"],
  "scopes": [
    {
      "resource_pattern": "public.analytics_*",
      "description": "Read-only access to analytics tables"
    },
    {
      "resource_pattern": "public.reports_*",
      "description": "Read-only access to reports tables"
    }
  ]
}

Scope Fields

Field	Type	Description
`resource_pattern`	string	Glob pattern matching resources within the tool.
`description`	string	Human-readable description of what this scope grants.

Scope Pattern Examples

Tool	Scope Pattern	Matches
PostgreSQL	`public.users`	Only the `users` table in the `public` schema
PostgreSQL	`public.analytics_*`	All tables starting with `analytics_`
S3	`my-bucket/reports/*`	Objects in the `reports/` prefix
S3	`my-bucket/exports/*.csv`	Only CSV files in the `exports/` prefix
GitHub	`org/repo-*`	Repositories matching `repo-*` in the org
HTTP	`https://api.internal.com/v1/*`	Only v1 API endpoints

Managing Permissions

List Agent Permissions

curl https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "perm_8k2m4n",
      "agent_id": "agt_sales-bot",
      "tool_id": "tool_crm_8k2m",
      "tool_name": "internal-crm-api",
      "mode": "allow",
      "operations": ["read", "list"],
      "rate_limit": {
        "max_per_minute": 60,
        "burst": 10
      },
      "max_payload_bytes": null,
      "time_window": null,
      "scopes": [],
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    },
    {
      "id": "perm_9j3n5p",
      "agent_id": "agt_sales-bot",
      "tool_id": "tool_shell_builtin",
      "tool_name": "shell",
      "mode": "deny",
      "operations": [],
      "rate_limit": null,
      "max_payload_bytes": null,
      "time_window": null,
      "scopes": [],
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_perm001",
    "timestamp": "2026-03-01T10:05:00Z",
    "next_cursor": null,
    "total": 2
  }
}

Set a Permission

curl -X PUT https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "tool_crm_8k2m",
    "mode": "allow",
    "operations": ["read", "write", "list"],
    "rate_limit": {
      "max_per_minute": 120,
      "burst": 20
    },
    "max_payload_bytes": 1048576,
    "scopes": [
      {
        "resource_pattern": "contacts/*",
        "description": "Access to contact resources"
      },
      {
        "resource_pattern": "deals/*",
        "description": "Access to deal resources"
      }
    ]
  }'

Response:

{
  "data": {
    "id": "perm_8k2m4n",
    "agent_id": "agt_sales-bot",
    "tool_id": "tool_crm_8k2m",
    "tool_name": "internal-crm-api",
    "mode": "allow",
    "operations": ["read", "write", "list"],
    "rate_limit": {
      "max_per_minute": 120,
      "burst": 20
    },
    "max_payload_bytes": 1048576,
    "time_window": null,
    "scopes": [
      {
        "resource_pattern": "contacts/*",
        "description": "Access to contact resources"
      },
      {
        "resource_pattern": "deals/*",
        "description": "Access to deal resources"
      }
    ],
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "meta": {
    "request_id": "req_perm002",
    "timestamp": "2026-03-01T12:00:00Z"
  }
}

Bulk Set Permissions

Set multiple permissions for an agent in a single request:

curl -X PUT https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions/bulk \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      {
        "tool_id": "tool_crm_8k2m",
        "mode": "allow",
        "operations": ["read", "list"]
      },
      {
        "tool_id": "tool_sendgrid_builtin",
        "mode": "allow",
        "operations": ["send"],
        "rate_limit": { "max_per_minute": 10, "burst": 3 }
      },
      {
        "tool_id": "tool_shell_builtin",
        "mode": "deny"
      },
      {
        "tool_id": "tool_s3_builtin",
        "mode": "deny"
      }
    ]
  }'

Response:

{
  "data": {
    "created": 2,
    "updated": 2,
    "total": 4
  },
  "meta": {
    "request_id": "req_perm003",
    "timestamp": "2026-03-01T12:05:00Z"
  }
}

Delete a Permission

Remove a specific permission, reverting to the default behavior:

curl -X DELETE https://api.mitrity.com/api/v1/agents/agt_sales-bot/permissions/perm_8k2m4n \
  -H "Authorization: Bearer mk_live_your-api-key"

Permission Evaluation Order

When the gateway evaluates an agent action, permissions are checked in this order:

Explicit deny: If a deny permission exists for the agent-tool pair, the action is denied immediately.
Explicit allow: If an allow permission exists, check operations, rate limits, payload limits, time window, and scopes. If all checks pass, the action proceeds to policy evaluation.
Default mode: If no permission exists, apply the tenant default mode (deny or allow).
Policy evaluation: If the action passes the permission check, it proceeds to policy evaluation.

Agent Action
    │
    ▼
Explicit Deny? ──Yes──► DENIED
    │ No
    ▼
Explicit Allow? ──Yes──► Check constraints ──Pass──► Policy evaluation
    │ No                      │ Fail
    ▼                         ▼
Default Mode                DENIED
    │
    ├── default_deny ──► DENIED
    └── default_allow ──► Policy evaluation

Dashboard Management

Viewing Permissions

Navigate to Agents > [Agent Name] > Permissions to see all tool permissions for an agent. The permissions view shows:

All explicitly granted and denied tools
Active rate limit status (current usage vs limit)
Time window status (active or inactive)
Scope details

Editing Permissions

Click on any permission to modify it. Changes take effect immediately — the gateway receives updated permissions within seconds via the heartbeat channel.

Permission Templates

Create permission templates for common agent roles:

Read-Only Agent: Allow read and list on specified tools, deny everything else
Data Processing Agent: Allow read/write on databases, deny code execution and network
Customer Support Agent: Allow CRM read, email send, deny bulk operations

Templates are available at Tools > Permission Templates.

Best Practices

Use Default Deny

Configure your tenant with default_deny mode. This ensures agents can only access tools explicitly granted to them, following the principle of least privilege.

Start with Read-Only

When onboarding a new agent, start with read-only permissions and expand as needed. This lets you observe the agent's behavior before granting write access.

Set Rate Limits on All Tools

Even for trusted agents, set rate limits as a safety net. An agent stuck in a loop can generate thousands of requests per minute without rate limits.

Use Scopes for Sensitive Data

Instead of granting broad database access, use scopes to limit access to specific tables. An analytics agent should not need access to the users or credentials tables.

Review Permissions Regularly

Set a quarterly review cadence for agent permissions. Remove permissions for tools that are no longer used and tighten scopes based on actual usage patterns.

Document Time Windows

When using time windows, document the rationale. A future team member seeing a 02:00-06:00 window needs to understand it is for batch processing, not an arbitrary restriction.

Agent Permissions

Overview

Permission Modes

Allow Mode

Deny Mode

Default Behavior

Operations

Operation Filtering

Rate Limits

Rate Limit Fields

Rate Limit Recommendations

Payload Limits

Time Windows

Time Window Fields

Spanning Midnight

Scopes

Scope Fields

Scope Pattern Examples

Managing Permissions

List Agent Permissions

Set a Permission

Bulk Set Permissions

Delete a Permission

Permission Evaluation Order

Dashboard Management

Viewing Permissions

Editing Permissions

Permission Templates

Best Practices

Use Default Deny

Start with Read-Only

Set Rate Limits on All Tools

Use Scopes for Sensitive Data

Review Permissions Regularly

Document Time Windows

Related Documentation