Delegate scoped child keys without increasing authority

Define the worker’s job before its key

List the resources and operations the agent actually needs. A triage worker may need to read one inbox and create drafts; a tenant provisioning service may need project-wide inbox creation. Those roles should not share the same broad credential merely because they run in one application. Scope limits resource reach, while permissions limit operations. Both matter. Store a human-readable role name and intended owner with each delegated credential so an operator can revoke one worker without guessing which production job uses a generic agent key.

Select the narrowest resource boundary

Workspace keys operate within one workspace, subject to their permissions. POST /v0/projects/:project_id/api-keys creates a project-scoped key, and POST /v0/emails/inboxes/:inbox_id/api-keys creates an inbox-scoped key. A project key remains fenced to its project, while an inbox key cannot create another inbox. Some shared resources, including browser sessions, containers and app connections, require an organization key. Do not broaden every agent to workspace scope simply because one separate operational service needs a shared resource.

Understand inherited authority

A child key cannot gain permissions or resource scope beyond its creating key. Omitting permissions inherits the parent’s effective authority; it does not mean a new universally privileged credential. An explicit permission map that exceeds the parent or a scope outside its project or inbox is rejected. The autonomous bootstrap key lacks key-create permission, so it cannot mint its own escape hatch. Human claim leaves that original key restricted and provides a separate owner administration path for deliberate delegation.

Verify the delegated credential directly

After issuance, save key material privately and inspect GET /v0/auth/me using the new key. Check the returned workspace, scope and effective permission map against the intended role. Then perform an authorized read on the target resource and a safe negative test against an out-of-scope fixture in a local environment. Do not infer worker access from a successful owner request. A key that works against one inbox could still be broader than intended, so verify the declared scope as well as basic connectivity.

Rotate and revoke without losing ownership

Track api_key_id separately from raw secret material so you can revoke the right credential without logging it. DELETE /v0/api-keys/:api_key_id or the corresponding scoped route revokes access. Plan rotation by adding the replacement, updating the worker’s secret reference and retiring the old key deliberately. A registration replay does not resurrect a revoked original key. Do not copy a parent credential into child configuration as a fallback when a limited key receives a denial; that silently destroys the boundary you created.

Keep approval separate from authentication

A scoped key proves API authority at the resource boundary; it does not prove a human approved a particular email or app write. Bind external-action approval to the actual recipient, account and arguments. Your next step is a key inventory with role, scope, required permissions, issuing parent, rotation owner and revocation procedure, followed by a local negative test for each role.

Sources & verification

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

• Lupin child-key authority ↗Checked 2026-11-05
• Lupin key scopes and permissions ↗Checked 2026-11-05
• Lupin MCP scope behavior ↗Checked 2026-11-05

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