AI Agent Permission Matrix Template: Tools, Scopes, Data and Approval Thresholds

Most AI agents are approved on a description of what they will do, then given credentials that allow far more, and nobody can later say which tool, scope or data set was actually agreed. This template gives [Organisation] a single record per agent that lists every tool and operation the agent may call, the identity and scope each call runs under, the data it may touch, and the threshold at which a human must approve. It is the artefact that the risk assessment points to, that the platform team configures from, and that the access review checks against. It is for agent owners, IAM engineers and data owners. The reasoning behind authorisation models and approval design is in the linked guides; this page is the form you fill in.

How to use this template

• Replace text in square brackets, such as [Organisation], [Agent ID] and [30 days], with your own values. Bracketed numbers are illustrative, not standards.
• Complete one matrix per agent, not per model or per platform. Two agents on the same model with different tools are two matrices.
• Section 4 is the matrix. Copy tables 4.2 to 4.5 into your agent registry, GRC tool or a version-controlled file next to the agent's configuration. A matrix that lives only in a document drifts from what is configured.
• Every row must name where it is enforced (identity provider, tool server, gateway, policy engine). A row enforced only by the system prompt is not a permission and must be marked as such.
• Use it with the AI Agent Risk Assessment Template (which sets the tier) and the AI Agent Deployment Checklist (which checks the matrix is in place before go-live).

1. Purpose

This template records, for each AI agent at [Organisation], the minimum set of tools, operations, scopes and data needed for its stated purpose, and the conditions under which an action needs human approval. It turns the least privilege principle (NIST SP 800-53 AC-6) into a reviewable list that can be compared with what the agent's identity actually holds. OWASP LLM06:2025 Excessive Agency names three root causes: excessive functionality, excessive permissions and excessive autonomy. Sections 4.2, 4.3 and 4.5 of the matrix address each of them in turn.

2. Scope

A matrix is required for any agent at [Organisation] that can call a tool, API, MCP server or another agent, including:

• Agents built on internal frameworks or cloud agent services.
• Agents built on low-code platforms by business users.
• AI coding agents that can run commands, change repositories or call cloud APIs.
• Third-party agents that hold OAuth grants, API keys or accounts in [Organisation] systems.

Text-only assistants with no tool access are out of scope until a tool is added. Adding a tool is a change under section 6.

3. Roles and responsibilities

Microsoft Entra Agent ID, for example, records a sponsor as the human accountable for an agent's lifecycle and access decisions. Where your platform has such a field, the sponsor in 4.1 must match it.

4. The permission matrix

4.1 Agent record

4.2 Tool and operation matrix

One row per tool operation, not per tool. A "files" tool with read, write and delete is three rows, each justified separately. Operations the agent must never perform are listed too, marked Deny, so reviewers can see the decision was made.

Rules for completing 4.2:

• Scope column: write the exact scope, role or permission string the identity is granted, never a description. Wildcards (*, admin, full_access) are not permitted without an exception under section 5.
• Context column: "User" means the call uses a delegated token and the user's own permissions; "Agent" means the agent's own identity. OWASP LLM06 recommends that actions taken for a user run in that user's context with the minimum privileges needed.
• Token audience: for MCP servers, record the canonical server URI. The MCP authorisation specification (version 2026-07-28) requires clients to send it as the RFC 8707 resource parameter and servers to accept only tokens issued for them, so one token cannot be replayed at another tool.
• Risk level: use the four levels in 4.5. Unmapped operations default to High.
• Delegation: if the agent obtains tokens by OAuth 2.0 Token Exchange (RFC 8693), record whether the issued token represents delegation (the agent keeps its own identity, shown in the act claim) or impersonation. Prefer delegation, so downstream logs show both parties. See the OAuth Token Exchange and Delegation Guide.

4.3 Data access matrix

• Retrieval must respect source permissions: an agent that searches an index built with a privileged account can show a user documents they could not open directly. Record the filter that prevents it. See the Vector Database Security Guide.
• Memory column: state whether data from this source may be written to long-term memory and for how long. The OWASP AI Agent Security Cheat Sheet recommends isolating memory between users and sessions and setting expiry. See the AI Agent Memory Security Guide.
• Egress column: "Can leave" covers sending, posting, uploading and calling external URLs with the data as a parameter.

4.4 Limits

The MCP tools specification requires servers to rate limit tool invocations; this table sets the values. In Microsoft Entra ID Governance, an access package assigned to an agent identity with an end date notifies the sponsor before expiry and removes access if no extension is approved, which is one way to enforce the last row. Spend and per-action limits are covered in depth in the AI Agent Action Approvals and Spending Limits Guide.

4.5 Approval thresholds

The OWASP AI Agent Security Cheat Sheet uses the same four levels and makes unmapped tools require review, so unknown operations fail closed. It also warns that approval must be enforced outside the agent: an approval should be bound to the exact action, time-limited and usable once, not a flag the agent can set. For approval mechanisms see the Human-in-the-Loop for AI Agents Guide.

5. Exceptions

1. Any wildcard scope, standing admin role, Critical operation set to Allow without per-action approval, or row enforced only in the prompt is an exception.
2. The owner records the business reason, the compensating control (for example a separate approval service or additional monitoring) and an expiry no later than [90 days].
3. [AI governance body] approves or rejects. Approved exceptions appear in the matrix with an "EXC" reference.
4. Expired exceptions revert to Deny. They are not renewed automatically.

6. Review and change control

• Change triggers: a new tool or MCP server, a new operation on an existing tool, a model or framework change, a new data source, a change of execution context, or a new sub-agent. Each requires an updated matrix approved before the configuration change (NIST SP 800-53 CM-3).
• Periodic review: every [90] days for Tier 3, [180] for Tier 2, [365] for Tier 1. The reviewer compares the matrix with the permissions the identity actually holds and with usage logs, and removes rows that were not used. The method is in the Agent Permission Drift guide.
• Tool list changes: MCP servers can notify clients when their tool list changes. Treat a changed tool list from a server as a change trigger, not as automatic approval.
• Retirement: when the agent is retired, the matrix is the list of everything to revoke. Close it with the decommissioning evidence. See the NHI Offboarding and Decommissioning Guide.

7. Sign-off

Implementation guidance

Rolling it out

1. Start with the riskiest agents: complete matrices first for agents with write, send, delete or admin operations, and for any agent that reads untrusted content such as email or web pages.
2. Build from what is granted, then cut: export the agent identity's current roles, scopes and OAuth grants, list them as rows, and ask the sponsor to justify each one. Unjustified rows become Deny.
3. Test in a non-production tenant: apply the reduced permissions, run the agent's normal tasks and record any 403 insufficient_scope responses. Under the MCP specification these responses should name the scopes the operation needs, which tells you exactly which row is missing.
4. Make it a gate: configure the identity issuance or access package workflow so that an agent identity is issued, or its access extended, only against an approved matrix version.
5. Roll back safely: if a reduced matrix breaks a business process, restore the single missing row with a time-limited exception rather than reinstating the old role.

Choosing how fine-grained to go

• OAuth scopes: enough where the API offers narrow scopes per operation. Record the scope string in 4.2.
• Rich authorisation details: where a single scope is too coarse (for example "write any file"), RFC 9396 Rich Authorization Requests lets a client request authorization_details with actions, locations, datatypes and an identifier for one resource. Use it where your authorisation server supports it. See the OAuth Rich Authorization Requests (RAR) Guide.
• Policy engine or gateway: needed when limits depend on parameters (recipient domain, amount, record count). Record the policy name in the "Enforced at" column. The AI Agent Authorisation Guide compares the models.
• Small and large organisations: a small team can keep matrices as a spreadsheet tab per agent and focus on 4.2 and 4.5. A large organisation should store them as structured data in the agent registry so drift detection can compare them automatically with granted permissions.

What the matrix catches

• Instructions are not permissions: in the Replit AI agent database deletion a code freeze existed only as a natural-language instruction while the agent's workflow still held write access to production. A matrix row of "Delete production data: Deny, enforced at database role" would have recorded the freeze as a permission change, not a request.
• Trialled tools left in place: OWASP LLM06 gives the example of an extension trialled in development and dropped, but still available to the agent. Listing Deny rows and removing unused rows at review prevents it.
• Untrusted tool metadata: the MCP tools specification says clients must treat tool annotations as untrusted unless they come from trusted servers. Set the risk level in 4.2 yourself; do not copy it from a tool's own description.

Measuring it

• Percentage of production agents with an approved, current matrix.
• Percentage of granted scopes and roles that map to an Allow row (target 100 per cent).
• Rows unused in the last review window, and how many were removed.
• Critical operations set to Allow without per-action approval (target zero outside approved exceptions).
• Open exceptions and their average age.

Framework mapping

Standards and references

• OWASP: Top 10 for LLM Applications 2025 (LLM06 Excessive Agency)
• OWASP Cheat Sheet Series: AI Agent Security Cheat Sheet
• Model Context Protocol: Authorization specification
• Model Context Protocol: Tools specification
• IETF: RFC 9396, OAuth 2.0 Rich Authorization Requests
• IETF: RFC 8693, OAuth 2.0 Token Exchange
• Microsoft Learn: Governing agent identities with Microsoft Entra ID Governance
• NIST: SP 800-53 Rev. 5, Security and Privacy Controls

This template is provided for guidance and must be adapted to your organisation. Related NHI Mgmt Group resources: Identity Governance for AI Agents Guide · AI Agent Tool and Plugin Security Guide · MCP Security Guide · AI agent registry