--- title: "Which API key permissions does an AI agent need?" description: "The smallest API key for each AI agent job, from sending receipts to running campaigns, what no key can ever do, and the 403 a missing permission returns." url: https://www.unitpost.com/blog/agents/api-key-permissions-for-ai-agents section: Blog updated: 2026-11-02 --- # Which API key permissions does an AI agent need? Give each agent its own key with only the permissions its job needs. An agent that sends receipts needs a Sending key; one that writes a weekly report needs Read only; one that runs campaigns needs the campaign permissions and nothing for contacts it doesn't change. On Unitpost no key, even Full access, can create keys, change the team or touch billing, and a missing permission comes back as 403 insufficient_scope. ## Which API key permissions does an AI agent need? > The smallest API key for each AI agent job, from sending receipts to running campaigns, what no key can ever do, and the 403 a missing permission returns. An agent with a key can do whatever the key allows, as often as its loop runs. So the question for each agent isn't "what might it need" but "what is the least it needs for this job", decided per agent, before it runs. ### Which permissions does each agent job need? Unitpost permissions are capabilities named `resource:action`. A key starts from a preset (Full access, Sending or Read only) or, on paid plans, from a list you tick yourself. For common agent jobs: - Sends receipts, resets and notifications from your app: the Sending preset. It can send email, campaigns and SMS, emit events, and read what a send needs (contacts, templates, domains, suppressions). It can't create, edit or delete anything. - Writes a weekly deliverability report: Read only. `email_stats`, the bounce and complaint lists and `email_domains_diagnose` all need only reads (`emails:read`, `suppressions:read`, `domains:read`). - Reads replies and answers them: `emails:read` to list and read received mail, and `emails:send` to reply. Nothing else. - Drafts a campaign for a person to approve: `campaigns:write`, plus `templates:read` and `segments:read` to pick the content and audience. Leave out `campaigns:send`, and the person sends it from the dashboard. - Runs approved campaigns end to end: add `campaigns:send`, and keep an approval step in your code (how (/blog/agents/ai-agent-approval-before-send)). - Keeps contacts in sync with your app: `contacts:write` and `topics:write`, without any send permission. - Sends texts: `sms:send` and `sms:read`. Buying numbers is separate (below). > **Name keys after the agent:** "support-agent replies" or "weekly-report (read only)" tells the next person what to revoke. Each key's usage shows which agent made which calls. ### What can no key do, even Full access? Some permissions are never given to keys, whatever preset or list you choose: - creating or revoking API keys; - inviting, removing or changing teammates; - billing and plan changes; - deleting the workspace. Creating and revoking keys needs a person in the dashboard: an API-key call to those endpoints gets `401`. That is the point. A leaked key can't make more keys, and it can't revoke yours. Four more are key-usable but off in every preset, including Full access: changing the workspace's branding and name, reading other keys, reading the activity log, and buying SMS numbers. Someone has to tick them, and only a member who holds the permission can give it to a key. A key that buys numbers also needs a monthly spending cap that only the owner sets, so with no cap every purchase by API is refused. ### What does the agent see when a permission is missing? A call outside the key's permissions fails before it does anything: ```bash { "error": { "code": "insufficient_scope", "message": "This API key isn't allowed to 'campaigns:send'. Use a key with the required scope." } } ``` The status is `403`, over REST and over MCP alike; an OAuth sign-in gets the same code with a message saying to sign in again and allow the permission. Tell the agent, in its instructions, to stop and report a `403` instead of retrying: no retry will change the answer, and the message names what to add. ### Key or OAuth for an agent? An MCP client that a person connects in a browser (Claude, Cursor, ChatGPT) signs in with OAuth instead of a key. The person picks the permissions on the consent screen, with a Read only button, and the access belongs to them: removing them from the workspace ends it. A token refresh never adds permissions. Keys suit agents that run where nobody can click Approve: servers, CI jobs and containers (OAuth or API key (/blog/agents/mcp-oauth-vs-api-key)). ### How do you give an agent a smaller key later? Permissions are fixed when a key is created. To narrow one, create a new key with the smaller set, deploy it to the agent, check its first calls succeed, then revoke the old key. For SMTP, Settings → SMTP makes a send-only credential the same way. ## FAQ ### Can an AI agent create or revoke API keys? Not on Unitpost. Creating and revoking keys needs a person signed in to the dashboard with the Manage API keys permission. A call with any API key gets 401, so a leaked key can't mint more keys or revoke the ones locking it out. ### What happens when an agent's key lacks a permission? The request fails with 403 and the error code insufficient_scope, and nothing runs. The same code comes back over REST and over MCP, so an agent can tell the person which permission to add instead of retrying. ### Should every agent get its own key? Yes. A key per agent means you can revoke one without stopping the others, and each key's usage shows which agent made which calls. Name the key after the agent and the job. ### Is OAuth safer than an API key for an agent? It's tied to a person rather than the workspace, and the person picks the permissions on the consent screen, Read only included. Use it when someone connects an MCP client in a browser; use a key where nothing can open one, such as a CI job or a server. ## Related - [Gmail, Yahoo and Microsoft bulk sender requirements](https://www.unitpost.com/blog/deliverability/bulk-sender-requirements-gmail-yahoo-microsoft): What Gmail, Yahoo and Outlook.com require from bulk senders: SPF, DKIM, aligned DMARC, one-click unsubscribe and a spam rate under 0.3%. - [Can an AI agent have its own email address?](https://www.unitpost.com/blog/agents/can-ai-agents-have-email-address): Three ways to give an AI agent an email address: a person's mailbox, an inbox-per-agent product, or your own domain with inbound routing and a send API. - [Get an email or a text when Claude Code finishes a task](https://www.unitpost.com/blog/agents/claude-code-notify-email-sms): Claude Code Stop and Notification hooks that run the unitpost CLI: an email when Claude finishes, a text when it waits for your approval.