Mailbox-Scoped API Keys for Multi-Customer Agent Platforms
Use mailbox-scoped API keys to separate customer inbox access: provisioning vs runtime credentials, ownership checks, negative tests and rotation.
John Joubert
Founder, Robotomail

Table of contents
- The example: RelayDesk, Cedar and Harbor
- Two roles, two kinds of credential
- Where mailbox-scoped API keys enforce the boundary, and where they don't
- Issuing a scoped key after an ownership check
- What a scoped key can and can't do
- Negative access tests
- Rotation and revocation
- Shared-account limits you still own
- FAQ
- Next step
Mailbox-scoped API keys let a platform give each customer's agent a credential that works only for that customer's mailbox, while a trusted backend keeps the full-access key that creates mailboxes and keys. The key's scope is enforced by Robotomail. Deciding which mailbox belongs to which customer is still your application's job. Your platform has to authorize the customer and agent against its own records before it issues a key or makes a call on their behalf.
This post works through that boundary with a fictional platform, the access checks that must fail, and how to rotate and revoke keys without leaving a gap.
The example: RelayDesk, Cedar and Harbor
RelayDesk is a fictional platform that runs enquiry-handling agents for businesses. Two fictional customers, Cedar and Harbor, each have a lead qualification agent with its own mailbox. RelayDesk holds one Robotomail account that contains both mailboxes.
RelayDesk stores its own mapping table (application-owned, not a Robotomail feature):
| customer_id | agent_id | mailbox_id | mailbox_address | credential_secret_ref | lifecycle_state |
|---|---|---|---|---|---|
| cus_cedar | qualifier | mbx_cedar_q | cedar-qualifier@robotomail.co | secrets/cedar/qualifier/runtime | active |
| cus_harbor | qualifier | mbx_harbor_q | harbor-qualifier@robotomail.co | secrets/harbor/qualifier/runtime | active |
(customer_id, agent_id) is unique. Conversation and run records are keyed by mailbox_id and thread_id. The table holds a reference to a secret store entry, never the key itself.
Two roles, two kinds of credential
Split credentials by who uses them:
- Provisioning service (trusted, platform-held). It holds a full-access Robotomail key. It creates mailboxes, issues and revokes keys, and manages domains. Only a small backend service can reach it.
- Runtime agent workers. Each worker receives only the mailbox-scoped key for the mailbox it is assigned. It sends, reads and handles that mailbox's mail, and nothing else.
Neither key belongs in a browser bundle, a model prompt, a customer-visible log or a repository. Agents should not see their own key in the context window either. The worker process injects it into HTTP calls outside the model's reach. The agent email security guide covers the wider handling rules. This post stays on the authorization boundary.
Where mailbox-scoped API keys enforce the boundary, and where they don't
Robotomail enforces two things:
- The Robotomail account that owns the mailbox.
- The mailbox scope attached to an API key.
Robotomail does not know that mbx_cedar_q belongs to Cedar. From its side, RelayDesk owns both mailboxes, so RelayDesk's full-access key can operate on either one. If your web app takes a mailbox ID from a browser request and passes it to the provisioning service, the account check will succeed for any mailbox RelayDesk owns.
So the rule is: never accept a browser-supplied mailbox ID as proof of ownership. Resolve the mailbox from the authenticated customer and agent using your own table, then act.
Issuing a scoped key after an ownership check
Key creation takes a name and a mailboxIds array, authenticated with the platform's full-access key. The exact request and response shapes are in the API Keys reference, and the scoping rules are in key scoping.
One detail matters a lot here. In the current implementation, omitting mailboxIds or passing an empty array creates a full-access key. That means a missing tenant lookup that turns into an empty list would quietly produce your most powerful credential. Your code has to refuse that case before the request is sent.
Application-owned pseudocode for RelayDesk's provisioning service:
# RelayDesk application code (not a Robotomail SDK feature)
def authorize_customer_agent(user, agent_id) -> list[str]:
"""Return mailbox IDs this authenticated user's customer owns for agent_id."""
row = db.agent_mailboxes.get(customer_id=user.customer_id, agent_id=agent_id)
if row is None or row.lifecycle_state != "active":
return []
return [row.mailbox_id]
def issue_runtime_key(user, agent_id):
mailbox_ids = authorize_customer_agent(user, agent_id)
if not mailbox_ids:
# Never fall through: an empty list would mean a full-access key.
raise PermissionDenied("no owned, active mailbox for this agent")
allowlist = db.agent_mailboxes.ids_for_customer(user.customer_id)
if not set(mailbox_ids).issubset(allowlist):
raise PermissionDenied("mailbox not owned by customer")
result = provisioning_client.create_key( # wraps the documented API Keys call
name=f"{user.customer_id}-{agent_id}-runtime",
mailbox_ids=mailbox_ids,
)
if result.scoped is not True:
provisioning_client.revoke_by_prefix(result.prefix)
raise RuntimeError("expected a scoped key")
secret_store.put(f"secrets/{user.customer_id}/{agent_id}/runtime", result.key)
# Do not log `result`. Store the key once, keep only metadata elsewhere.
The creation response returns the key, its prefix and a scoped flag. Write the key straight into your secret store, check that scoped is true, and never log the response body. There are no finer-grained scopes like read-only. A key is either scoped to mailboxes or full access.
What a scoped key can and can't do
| Operation | Mailbox-scoped key | Full-access key |
|---|---|---|
| List mailboxes | Only its own | All in account |
| Send and read messages | Its mailboxes only | Any mailbox |
| Update its mailbox settings (including pause and reactivate) | Yes | Yes |
| Manage webhooks for its mailboxes | Yes | Yes |
| Create or delete mailboxes | No | Yes |
| Account, billing and domain operations | No | Yes |
| Create or revoke API keys | No | Yes |
| Upload attachments | No | Yes |
Mailbox scope is not read-only, and it doesn't limit an agent to a single action. A compromised runtime key for Cedar can pause Cedar's mailbox or repoint its webhook. If your product needs tighter limits than that, such as "this agent may only reply in existing threads," enforce them in your worker or proxy.
Negative access tests
Write tests that prove the wrong requests fail. Run them in CI against a test account.
Test 1: Harbor asks for Cedar's mailbox
Harbor's user, logged into RelayDesk, sends a request referencing mbx_cedar_q. RelayDesk resolves (cus_harbor, qualifier) from the session, gets mbx_harbor_q, and rejects the mismatch. The denial happens before any Robotomail call. The provisioning key would technically be allowed to touch Cedar's mailbox, which is exactly why this check has to live in RelayDesk.
Test 2: Cedar's scoped key against Harbor's mailbox
curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_harbor_q/messages \
-H "Authorization: Bearer $CEDAR_RUNTIME_KEY" \
-H "Content-Type: application/json" \
-d '{"to": ["vendor@example.com"], "subject": "Scope test", "bodyText": "This request should be denied."}'
Test 3: Cedar's scoped key tries to provision
curl -X POST https://api.robotomail.com/v1/mailboxes \
-H "Authorization: Bearer $CEDAR_RUNTIME_KEY" \
-H "Content-Type: application/json" \
-d '{"address": "cedar-extra"}'
Assert that both requests are rejected and that nothing was sent or created. Don't hardcode one specific status code. Depending on the resource and auth path, a denial can surface as a different error, so assert "not a success" and check the error body against the documented errors. Also add a positive control: Cedar's key sending from mbx_cedar_q should be accepted. Keep in mind that acceptance means the API took the message, not that it was delivered.
Rotation and revocation
Only the full-access provisioning service can rotate keys. Scoped keys can't mint their own replacements.
- Re-run the ownership check and build the same explicit, nonempty
mailboxIdslist. Don't copy it from the old key without validating it again. - Create the replacement key and confirm
scopedis true. - Write it to the secret store under the same reference, then roll the worker so it picks up the new value.
- Verify that the worker can reach its intended mailbox and still fails the negative tests.
- Find the old key. Listing keys returns
id,name,prefixandenabledmetadata. The creation response has noid, so match the old record by its stored prefix and name, confirm it's the one you mean, then revoke it by ID.
If a key is compromised or a customer offboards, revoke it right away and stop the platform from running that agent. Don't assume that deleting a customer row in your database, or anywhere else, revokes their keys. Revocation is an explicit call your offboarding code has to make.
Shared-account limits you still own
One Robotomail account means some things stay shared no matter how keys are scoped:
- Billing and provisioning authority belong to RelayDesk's account. There's no per-customer spend cap or automatic tenant lifecycle.
- Inbound allowance is pooled across the account. One busy customer uses up capacity the others share.
- Application authorization, runtime isolation, data retention and any billing to your customers are your responsibility.
Mailbox scoping reduces API access. It isn't complete tenant isolation.
Do the plan math with every mailbox counted, including the signup mailbox and any test or operations mailbox. On current terms, Starter is $19/month with 10 total mailboxes, one custom domain, 500 sends/day and 15,000 sends/month per mailbox, and 2,000 inbound/month across the account. Growth is $79/month with 50 mailboxes, five custom domains, 1,000 sends/day per mailbox with no monthly send cap (daily and rate limits still apply), and 20,000 inbound/month across the account.
Ten customers with two agent mailboxes each need 20 mailboxes, so Starter doesn't fit. Growth fits that mailbox count only if the shared inbound volume, storage and custom-domain count also fit. Add your model and hosting costs on top. These are capacity checks, not cost-per-customer figures, and current terms live on pricing.
FAQ
Does Robotomail know which of my customers owns a mailbox?
No. It knows your account owns the mailbox and which mailboxes a key is scoped to. The mapping from customer to mailbox lives in your database, and your code must check it.
What happens if I create a key with an empty mailbox list?
In the current implementation you get a full-access key. Treat an empty or missing list as an authorization failure and stop before calling the API.
Can a scoped key be read-only?
No. A scoped key can send, read, change its mailbox's settings and manage its webhooks. Put narrower rules in your worker or proxy.
Can a runtime worker rotate its own key?
No. Creating and revoking keys requires full access, so rotation runs through your provisioning service.
Next step
Create an account, provision two test mailboxes, issue one scoped key for each, and run the three negative tests above. Choose a multi-mailbox plan once that scope boundary and the shared limits match your product. Start at Robotomail.
Give your AI agent a real email address
Create a mailbox, connect your agent and test a conversation. Send, receive and retrieve the thread through one API.
Related posts

Route Incoming Email to the Right Customer Agent
Route incoming email from one Robotomail account to the right customer and agent: verify, map the mailbox, dedupe durably and resume the right run.
Read post
An Inbox for Every Customer's Agent: Lifecycle Design
Design repeat-safe provisioning for customer agent inboxes: mailbox boundaries, ID mapping, scoped credentials, reconciliation and deliberate retirement.
Read post
Build Email Into Your AI-Agent Platform
An end-to-end build: provision per-agent mailboxes, scope credentials, send, route inbound replies and resume the right customer's agent.
Read post