Adoption & Device Flow

Adoption lets you add new agents or CLI users to an existing tenant without requiring them to create a new account. Two flows are supported:

• Invite flow -- the tenant owner generates a token and shares it with the agent.
• Device flow -- the agent initiates the request and displays a short code for the owner to approve in the portal.

Both flows result in the agent receiving an API key scoped to the tenant (and optionally to specific mailboxes).

Invite flow

Use the invite flow when you control both sides of the handoff (e.g., you are provisioning an agent programmatically).

Step 1: Create an invite

The tenant owner creates an invite token via the portal API.

POST https://api.molted.email/v1/me/adopt/invite

curl -X POST https://api.molted.email/v1/me/adopt/invite \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-agent",
    "scopeAllMailboxes": true
  }'

To restrict access to specific mailboxes:

curl -X POST https://api.molted.email/v1/me/adopt/invite \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "support-agent",
    "scopeAllMailboxes": false,
    "mailboxScopes": [
      { "mailboxId": "MAILBOX_UUID", "permissions": ["read", "send"] }
    ]
  }'

{
  "token": "ma_inv_abc123...",
  "tokenPrefix": "ma_inv_",
  "expiresAt": "2026-04-01T12:00:00Z"
}

Tokens expire after 24 hours. The full token value is returned only once.

Step 2: Claim the invite

The agent presents the token to claim its API key.

POST https://api.molted.email/v1/adopt/claim

curl -X POST https://api.molted.email/v1/adopt/claim \
  -H "Content-Type: application/json" \
  -d '{"token": "ma_inv_abc123..."}'

{
  "apiKey": "mm_live_xyz...",
  "tenantId": "tenant-slug-a1b2c3d4",
  "mailboxScopes": []
}

Save apiKey immediately -- it is only returned once. Use it as your Authorization: Bearer token for all agent API calls.

Device flow

Use the device flow when the agent cannot receive a token directly (e.g., a CLI running locally that needs approval from the tenant owner).

Step 1: Initiate the device flow

The agent starts the flow without any credentials.

POST https://api.molted.email/v1/adopt/device

curl -X POST https://api.molted.email/v1/adopt/device \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "deviceCode": "dc_abc123...",
  "userCode": "ABCD-WXYZ",
  "expiresAt": "2026-03-31T12:30:00Z"
}

Display userCode to the user. They approve it in the portal at Settings > Pending Adoptions or at https://molted.email/adopt/ABCD-WXYZ.

Step 2: Poll for approval

GET https://api.molted.email/v1/adopt/device/:deviceCode/poll

curl "https://api.molted.email/v1/adopt/device/dc_abc123.../poll"

Poll every 5 seconds until the status is no longer pending. Polling too frequently may be throttled.

Step 3: Owner approves

The tenant owner approves the device from the portal or via the API:

POST https://api.molted.email/v1/me/adopt/device/:userCode/approve

Managing adoptions

List pending adoptions

GET https://api.molted.email/v1/me/adopt/pending

Get device info

GET https://api.molted.email/v1/me/adopt/device/:userCode/info

Revoke an adoption

DELETE https://api.molted.email/v1/me/adopt/:id

Revoking an adoption invalidates the token. Any API key issued from that token stops working.

Mailbox scopes

Both flows support optional mailbox scoping. When scopeAllMailboxes: false is set on the invite, only the specified mailboxes are accessible with the issued key. See Authentication for permission values.

Related reading

• Authentication -- session cookies, Bearer keys, and programmatic signup
• Mailboxes -- mailbox management