Choose projects and inbox scopes for agent tenancy

Use the resource hierarchy deliberately

A Lupin workspace owns projects, API keys and resources. A project provides a namespace for inboxes, threads, drafts, domains, webhooks, lists and metrics. An inbox identifies one communication address and its email resources. This hierarchy gives an agent service several isolation choices without requiring one workspace per process. Start with customer ownership and operational accountability: a customer project with multiple purpose-specific inboxes often maps better to the domain than a new project for every model run or a shared inbox for unrelated customers.

Keep tenant mapping outside model choice

Persist the application tenant, organization_id and project_id in trusted server-side state. Select the credential from that mapping when constructing a job. The model may identify a candidate resource from received content, but it must not choose another tenant’s key or replace the authenticated organization. Include inbox_id in email jobs and verify it belongs to the selected project before exposing content. A subject line, arbitrary metadata field or sender-supplied project identifier is useful context only after your application checks the authorized resource relationship.

Use scoped routes and keys together

Project routes include /v0/projects/:project_id/emails/inboxes and related thread, draft, domain and webhook paths. A scoped key remains fenced even when it calls an organization-level route, while explicit scoped paths make client intent easier to audit. A project key can create inboxes in its own project if permissions allow; an inbox key cannot create a new inbox. Org-level list endpoints can span projects for a properly authorized operator. Avoid giving workers that broader view unless their task actually needs cross-project administration.

Separate shared workspace resources

App connections, containers and browser sessions require organization keys because they are shared workspace resources in the current API. Do not imply that an inbox key can operate a connected human account just because it can read that account’s email requests. Put shared-resource execution behind a distinct service that validates tenant intent, account selection and approval. This lets routine mailbox workers remain narrowly scoped while a reviewed action crosses into an explicitly owned shared resource boundary. The larger credential belongs in that controlled service, outside model context.

Treat deletion and transfer as lifecycle decisions

Deleting a project cascades into its inboxes, threads and messages, so tightly gate the destructive permission and keep an explicit retirement plan. Durable production organization moves are unsupported; a target workspace ID cannot transfer ownership. A human claim is the supported way to associate a human with an autonomous workspace. If your product needs a customer to leave, design an application-level export and retirement process around actual supported reads and deletions rather than promising a transfer endpoint that cannot preserve production ownership.

Validate the boundary with a matrix

Create synthetic tenant A and tenant B projects, each with one inbox and a scoped key. Check that each can read its own fixture and cannot read the other’s, including through org-level routes and MCP dispatch. Your next step is to make that mapping visible in operations so the selected credential, project and inbox can be checked before any agent sees customer content.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin projects and namespace ↗Checked 2026-11-05
• Lupin authentication scopes ↗Checked 2026-11-05
• Lupin organization lifecycle ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.