Free tool · runs in your browser
OAuth scope planner: the minimum permissions for an AI agent
permission-planner is an open-source tool that turns a list of intended AI-agent actions into the minimum OAuth scopes and API permissions, a risk tier, and a recommended human-approval policy, with every scope traced to the provider's official documentation.
Try permission-planner
Choose the actions your agent will take. The plan updates as you pick, entirely in your browser.
The interactive tool needs JavaScript. The same core runs locally: npx @teamshift/permission-planner
Who it is for
Developers requesting OAuth scopes for an agent or integration, security reviewers checking a consent screen, and owners deciding which of an agent's actions should wait for a person.
How it works
A curated catalog maps 89 agent actions across Google Workspace (Gmail, Calendar, Drive, Sheets), Microsoft Graph, Slack, HubSpot, QuickBooks Online, Stripe restricted keys and the Shopify Admin API to the scopes each needs. Each entry records the provider's sensitivity classification where one is published, a source link, and either a verification date or an explicit unverified flag.
The planner merges the scopes, drops a narrower scope only when the provider documents that a broader one you already need covers it, and sorts the actions into five risk tiers, each with an approval policy:
- read: automatic, with access logged
- write-internal: automatic with an audit log and an easy undo, spot-checked weekly
- send-external: a person approves each send until the agent has a clean track record
- money: always a person, with the amount and counterparty shown
- destructive: always a person; prefer soft delete
Example
An agent that reads Gmail and sends reminders needs gmail.readonly (Google classifies it restricted) and gmail.send (sensitive), not https://mail.google.com/, which is full mailbox access. QuickBooks Online has no read-only accounting scope at all, so the plan tells you to enforce read-only behavior inside the agent.
Limitations
- Seven providers and 89 actions. Anything else is reported as unknown, with close matches, and the planner never substitutes a broad scope.
- Stripe restricted-key labels and one Shopify entry are marked unverified. Confirm them against the linked docs before you ship.
- Scopes change. Each verified entry shows the date it was checked; the provider's page is the final word.
FAQ
What Gmail scope do I need to send email from an AI agent?
https://www.googleapis.com/auth/gmail.send. It is send-only, so it cannot read the mailbox, and Google classifies it as sensitive rather than restricted. Avoid https://mail.google.com/ and gmail.modify, which are both restricted and include reading.
Does QuickBooks Online have a read-only scope?
No. com.intuit.quickbooks.accounting grants read and write access to all accounting data, so read-only behavior and approvals have to be enforced inside the agent.
Which agent actions should always need human approval?
Moving money (charges, refunds, payouts, recording payments) and destructive actions (deleting records, files or email). External sends should need approval until the agent has a clean track record.
What if my action is not in the catalog?
The planner lists it as unknown, suggests close matches from the same provider, and never falls back to an admin or full-access scope. New entries are added by pull request with an official source URL.