AI Agent Permissions: Service, Action, and Data Scope

Quick answer: AI agent permissions are the policy design that translates an agent's task into three enforceable boundaries: which services it may reach, which actions it may take, and which records or environments it may touch. A named identity and a broker turn those boundaries into runtime checks rather than a one-time setup decision.

This guide is about authoring the policy itself. For the larger identity architecture, read IAM for AI agents. For the operating lifecycle around provisioning and review, see AI agent credential management.

Why "full access" is the default — and why that compounds

The first time a developer connects an AI agent to a service, full access is the path of least resistance. A Stripe admin key works immediately. A GitHub token with all repo scopes just works. Nothing breaks, so the scope question gets deferred.

The problem is that deferral compounds. Six months later you have:

• Four agents all authenticating with the same Stripe secret key
• No record of which agent made which API call when something goes wrong
• A GitHub token you can't revoke without checking every pipeline that uses it
• An agent that was added for a one-off task and was never removed — still active, still authorized

Granular permissions are hardest to retrofit. The pattern is easier to do right from the first agent than to fix across a dozen.

The three dimensions of agent permissions

There's no single "permission level" dial. Real granularity means thinking in three dimensions independently:

Service scope — which APIs the agent can reach at all. A support automation agent might need Zendesk and Stripe read-only. It has no business calling GitHub or your deployment API. Service scope is the first gate: if it's not listed, the request is denied before any other check.

Action scope — what the agent can do within a service. Stripe alone has more than 200 API endpoints. "Has Stripe access" is not a useful permission. Useful permissions are: can create payment intents, cannot issue refunds; can read customer records, cannot delete them; can create invoices, cannot void them. Action scope maps to the specific API operations the agent's task actually requires.

Data scope — which records the agent can touch within an action. A per-customer support agent should only be able to read the specific customer's subscription data, not the entire customer list. This is the hardest dimension to enforce at the API key level — most platforms don't support it natively, which is why brokered access matters.

Worked example: a Cursor agent with scoped Stripe access

Say you're building a Cursor agent that handles subscription inquiries: it can look up a customer's current plan and create a portal session so the customer can manage their billing.

What it needs:

• customers:read — look up customer records by ID or email
• subscriptions:read — check current subscription status
• billing_portal.sessions:write — create portal sessions

What it must not have:

• customers:write — cannot create or update customer records
• subscriptions:write — cannot change plans or cancel subscriptions
• refunds:write — cannot issue refunds
• payment_intents:write — cannot initiate charges

Stripe's restricted keys let you scope per resource category — customers, subscriptions, payment intents. That covers the action dimension well. The record-level dimension (this agent can only read records belonging to tenant X) isn't something static API keys can express — that scope has to be enforced at runtime by a layer that knows the agent's current task context.

Worked example: a GitHub agent for PR triage

An agent that monitors new PRs, labels them, and assigns reviewers needs:

• pull_requests:read — list and read open PRs
• pull_requests:write — add labels and request reviewers
• issues:read — read linked issues for context

What it must not have:

• repository:admin — cannot change repo settings, add collaborators, or modify branch protection
• contents:write — cannot push code directly
• actions:write — cannot create or modify GitHub Actions workflows

A GitHub fine-grained PAT lets you scope to specific repositories and specific permissions. The limitation is that it's still a static credential — it doesn't enforce data scope (which PRs the agent can label) or log which automated action triggered each API call.

Worked example: a Vercel deployment agent

A deployment agent that automatically deploys approved PRs needs:

• deployments:write — create new deployments
• deployments:read — check deployment status

What it must not have:

• projects:admin — cannot change project settings or environment variables
• domains:write — cannot reassign or transfer domains
• teams:admin — cannot manage team membership

Vercel's API tokens don't support granular scoping beyond read/write at the team level. This is the gap a broker fills: you connect a full Vercel token to the vault, then the broker enforces which operations the agent is permitted to call — denying requests that the token technically allows but the agent's policy doesn't.

When an agent needs broader access temporarily

Sometimes a task genuinely requires elevated permissions — a migration script, a one-time data export, an emergency fix. The right response isn't widening the agent's permanent scope. It's time-bounded elevation:

1. Create a new access profile with the elevated scope
2. Set a hard expiry — 1 hour, 24 hours, whatever the task window is
3. Use that profile for the specific task
4. Let it expire, or revoke it explicitly when done

This keeps the baseline profile narrow while still allowing one-off elevation. The elevated access shows up in the audit log with its own profile name, so there's a clear record of what happened and when it expired.

How to audit your existing agent permissions

If you're retrofitting granular permissions onto an existing agent stack, start with an inventory:

1. List every credential currently in use. Environment variables, config files, secrets managers, anywhere a key might be stored. The goal is a complete picture of what exists.
2. Map each credential to which agents use it. Shared credentials are your highest risk items — they have the widest blast radius and the least auditability.
3. For each agent, list the API calls it actually makes. Check your logs, or read the agent's code. Most agents use a small subset of what their key permits.
4. Create a named profile per agent with only the actions from step 3. Revoke the shared credential last, after all agents are migrated.
5. Review quarterly. Agents get added for tasks and never removed. A quarterly review catches stale profiles before they become a liability.

The audit sounds tedious but it usually only takes a few hours and the profile creation is straightforward. The hard part is step 2 — most teams don't know which credential is used by which system until they look.

Permission red flags to watch for

• Any agent using a *:admin or equivalent full-access key
• Multiple agents sharing a single credential (zero per-agent auditability)
• Credentials that haven't been rotated or reviewed in over a year
• Agents that were created for a one-off task and still have active credentials
• Service connections without a record of which agent uses them or why
• Any credential that appears in a codebase, config file, or conversation history

Each of these represents a gap between what you intend and what the access model actually enforces.

Setting this up with Gazebo

Gazebo's agent access model is built around this pattern: one access profile per agent, defined by service scope and action permissions, enforced at the broker layer. The underlying API key stays in the vault — the agent never sees it. When the agent authenticates, the broker checks its profile, returns a scoped credential for that specific call, and logs the access.

If an agent needs its permissions narrowed, you update the profile. If it needs to be shut down, you revoke the profile — the underlying service credential is untouched, and every other agent keeps running.

Documenting permissions for compliance and handoffs

Access profiles aren't just an operational tool — they're documentation. A well-named profile with a specific permission set tells the next developer exactly what that agent is supposed to be able to do, without them needing to read the agent's code or trace API calls in the logs.

For compliance purposes (SOC 2, HIPAA, ISO 27001), the access profile list functions as your agent access inventory. For HIPAA specifically, access profiles map directly to the §164.312 Technical Safeguards requirements — see HIPAA and AI agents for the full control mapping. For each profile, the record should include what the agent does, which services it can reach and what operations it can perform, when the profile was created and who owns it, and when access was last reviewed.

This documentation is easier to maintain when profiles are created with the assumption that someone else will need to understand and defend them later. "cursor-stripe-read" is better than "cursor-agent-1." A description field that says "Cursor session for billing inquiry workflow — reads customer and subscription data, creates portal sessions, no write access" is better than leaving it blank.

If you're preparing for a SOC 2 audit, the profile inventory is part of what your auditor will ask to see. See SOC 2 and AI agents for the full mapping between profile documentation and CC6 evidence requirements.

For the broader identity model this sits on, see IAM for AI agents. For a full checklist across all dimensions of agent security, see the AI agent security checklist.