Create a key for an agent

Give each agent its own key, scoped to what it needs. A leaked inbox key exposes one mailbox, not your whole organization. Each step shows the dashboard first and the API second.

1. Pick the scope

   The scope decides what the key can reach. It is fixed when you create the key.

   DashboardAPI

   Open machinemail.dev/app/api-keys?create=1. You can also go to API keys and choose Create key, or choose New API key in the command menu (⌘K).

   Give the key a Name that says which agent uses it, such as Support agent (prod). Then pick the Scope:

   • Organization (can mint keys): everything in the organization. Only organization keys can create other keys.
   • Inbox · followed by an address: that one inbox, its messages, threads and drafts. This is the best choice for a single agent.

   The route you create the key on sets its scope. Creating keys needs an organization key with api_key_create.

   Scope	Route
   Organization	POST /v0/api-keys
   Pod	POST /v0/pods/{pod_id}/api-keys
   Inbox	POST /v0/inboxes/{inbox_id}/api-keys

2. Pick the permissions

   Without a permission list, a key can do everything its scope allows. A list narrows it further.

   DashboardAPI

   Pick one of the Permissions presets:

   Preset	The key can
   Full access for the scope	Do everything its scope allows.
   Read only	Read inboxes and messages (inbox_read, message_read).
   Agent: read, send, label	Read, send, and change labels (inbox_read, message_read, message_send, message_update).

   Leave the inbound_raw box unticked for agents. It lets the key inject raw test mail, which is never authenticated.

   Pass permissions, an object of booleans or an array of names. Leave it out for full access within the scope.

   { "inbox_read": true, "message_read": true, "thread_read": true, "draft_create": true }

   API keys lists every permission.

   inbound_raw is never part of full access. Only the dashboard, or a key that already has inbound_raw, can grant it.

3. Create the key and copy it

   The full key is shown once. MachineMail stores only a hash of it.

   DashboardAPI

   1. Choose Create key.
   2. The Save your key dialog shows the key. Choose Copy.
   3. Store it somewhere safe, then choose I’ve saved it.

   curl https://api.machinemail.dev/v0/inboxes/support-agent@machinemail.dev/api-keys \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Support agent (prod)",
       "permissions": { "inbox_read": true, "message_read": true, "message_send": true, "message_update": true },
       "expires_at": "2027-01-01T00:00:00Z"
     }'

   The response’s api_key is the full key. It is never returned again.

   If you lose the key, revoke it and create another.

4. Give it to the agent

   Put the key in the agent’s secret store, never in a prompt or a file you share. The agent sends it as Authorization: Bearer followed by the key. An MCP client sends it the same way, as a header: see Client setup.

5. Revoke it when you’re done

   A revoked key stops working at once. Requests that use it get 401.

   DashboardAPI

   On API keys, find the key by its Name, the start of the Key, its Scope and when it was Last used. Choose Revoke, type DELETE and choose Revoke key.

   curl -X DELETE https://api.machinemail.dev/v0/api-keys/key_01m4fy8hmg0000dgevarwczcf7 \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY"

Troubleshooting

Related