> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Create, scope, rotate, and revoke Sendmux API keys.

API keys authenticate applications, scripts, mail clients, and automation. Keys are shown once when created or rotated, so store them in your secrets manager immediately.

Connected apps are different. They appear on the same credentials page for management, but they use short-lived tokens instead of manual API keys.

## Credential classes

| Credential class       | Created by                                       | Secret lifetime                                       | Where to manage it                                                                         |
| ---------------------- | ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Manual API key**     | A team member creates a key in Sendmux.          | Long-lived until you rotate or revoke it.             | **API Keys** with the **Manual keys** filter.                                              |
| **Connected app**      | You authorise an app through OAuth, such as MCP. | 15-minute access tokens with rotating refresh tokens. | **API Keys** with the **Connected apps** filter.                                           |
| **Agent access token** | An agent registers through agent access.         | Short-lived access token.                             | Agent access flow, then the **Agent access** card on the team page after owner acceptance. |

Revoking a manual API key stops that key. Disconnecting a connected app stops that app refreshing access and using its existing connection.

## Key types

| Key type               | Use it for                                                                            | Secret prefix |
| ---------------------- | ------------------------------------------------------------------------------------- | ------------- |
| **Infrastructure key** | Team automation, providers, routing, billing, logs, domains, mailboxes, and webhooks. | `smx_root_`   |
| **Sending key**        | Sending mail through the Sending API, SMTP, CLI tools, MCP clients, or agents.        | `smx_mbx_`    |
| **Mailbox key**        | API, IMAP, and SMTP access for one mailbox.                                           | `smx_mbx_`    |
| **Agent token**        | Constrained mailbox access for a self-registered agent.                               | `smx_agent_`  |

Sending keys and mailbox keys share the `smx_mbx_` prefix. Owner-approved agent tokens use `smx_agent_`. Permissions, token resource, and sending scope decide what each credential can do.

Pre-claim agent tokens include `mailbox.read` and `email.receive`, not `email.send`. After the owner joins and approves sending, the agent can request a Sending-resource `smx_agent_` token through [agent access](/docs/guides/agent-access).

Owners approve or revoke agent sending from the **Agent access** card on the
team page after accepting the agent invite.

<Note>
  Each team starts with **100 active credentials** across manual API keys and
  connected apps. See [Team limits](/docs/guides/team-limits).
</Note>

## Connected apps

Connected apps let tools such as MCP act with the product lines you authorise. During authorisation, you can choose Management, Mailbox, Sending, or a combination. If you choose Mailbox, you also choose the mailbox set the app can use. Sendmux then issues a short-lived access token for the app and a refresh token that rotates when used.

When a connected app asks for Management access, permissions are grouped by area, including Analytics, Billing, Domains, Email, Keys, Logs, Mailboxes, Providers, Routing, Team, and Webhooks. Each group can be set to **None**, **Read**, **Full**, or **Customise**, so you can review broad access quickly and open individual scopes only when needed.

Connected apps do not create `smx_root_` or `smx_mbx_` secrets. They are listed separately from manual API keys so you can see which app is connected, which product lines it can use, which mailbox set is selected, who authorised it, when it was last used, and how many requests it has made.

To manage connected apps:

<Steps>
  <Step title="Open API keys">
    Open **API Keys** in the team workspace.
  </Step>

  <Step title="Filter to connected apps">
    Use the credential filter and select **Connected apps**.
  </Step>

  <Step title="Disconnect an app">
    Select the disconnect action beside the app. This revokes its refresh token and grant immediately.
  </Step>
</Steps>

Re-authorising the same app updates the existing connection instead of creating unused manual API keys. If you choose fewer product lines or mailboxes during re-authorisation, removed tools and mailbox targets stop being available to that app.

## Create a key

<Steps>
  <Step title="Open API keys">Open **API Keys** in the team workspace.</Step>

  <Step title="Choose the key type">
    Select **Create API Key**, then choose the key type. Sending keys can route
    through all providers, selected providers, or delivery groups.
  </Step>

  <Step title="Store the secret">
    Copy the generated `smx_root_` or `smx_mbx_` value. Sendmux will not show it again.
  </Step>
</Steps>

## Scopes and presets

Infrastructure keys use role presets such as **Full Access**, **Read Only**, **Provider Admin**, **Billing Admin**, and **Webhook Admin**.

Sending and mailbox keys use mailbox permissions:

| Permission                | Allows                                |
| ------------------------- | ------------------------------------- |
| `email.send`              | Send email through HTTP or SMTP.      |
| `email.receive`           | Receive email through mailbox access. |
| `mailbox.read`            | Read mailbox folders and messages.    |
| `mailbox.settings.update` | Update mailbox identity and settings. |

## Rotate a key

Use rotation when a key may have leaked, when a team member leaves, or as part of regular credential hygiene.

1. Select the rotate action beside the key.
2. Copy the new secret when it appears.
3. Deploy the new secret to every system that uses it.
4. Revoke the old key once all callers have moved.

If your team is already at the API key limit, Sendmux requires the old key to be revoked during rotation.

## Revoke a key

Revocation is immediate. Any system still using the key loses access. Create and test a replacement before revoking a production key.

Mailbox keys also stop working while their mailbox is suspended, and work again after the mailbox is resumed.

## Related guides

<Columns cols={2}>
  <Card title="Send by HTTP" icon="code" href="/docs/guides/sending-via-http">
    Use a sending key to queue messages through the API.
  </Card>

  <Card title="Delivery groups" icon="route" href="/docs/guides/delivery-groups">
    Route sending keys through selected provider groups.
  </Card>

  <Card title="Mailboxes" icon="inbox" href="/docs/guides/mailboxes">
    Create mailbox keys and per-integration passwords.
  </Card>

  <Card title="API errors" icon="triangle-alert" href="/docs/api/errors">
    Handle authentication, permission, and rate-limit errors.
  </Card>
</Columns>