Mailbox-Scoped API Keys for Multi-Customer Agent Platforms

9 min read

Use mailbox-scoped API keys to separate customer inbox access: provisioning vs runtime credentials, ownership checks, negative tests and rotation.

John Joubert

John Joubert

Founder, Robotomail

Mailbox-Scoped API Keys for Multi-Customer Agent Platforms
Table of contents

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:

  1. 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.
  2. 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.

  1. Re-run the ownership check and build the same explicit, nonempty mailboxIds list. Don't copy it from the old key without validating it again.
  2. Create the replacement key and confirm scoped is true.
  3. Write it to the secret store under the same reference, then roll the worker so it picks up the new value.
  4. Verify that the worker can reach its intended mailbox and still fails the negative tests.
  5. Find the old key. Listing keys returns id, name, prefix and enabled metadata. The creation response has no id, 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