# Authenticating with Inboxkit

Inboxkit exposes two programmatic surfaces. Both act on the same account, workspaces, domains and mailboxes.

| Surface | Base | Auth | Best for |
|---------|------|------|----------|
| REST API | `https://api.inboxkit.com` | API key as a Bearer token | Scripts, backends, sequencer integrations |
| MCP server | `https://mcp.inboxkit.com/mcp` (Streamable HTTP) | OAuth 2.1 authorization code with PKCE | AI agents and assistants acting on a user's behalf |

Human-readable API documentation lives at https://docs.inboxkit.com. The MCP server's tools are listed in https://www.inboxkit.com/.well-known/mcp/server-card.json.

## REST API: API keys

1. Sign in at https://app.inboxkit.com and open **Settings, then API**.
2. Create an API key. It is shown once; store it as a secret.
3. Send it on every request:

```
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

4. Almost every endpoint is scoped to a workspace. Send the workspace UID in a header:

```
X-Workspace-Id: <workspace_uid>
```

Endpoints that are account-wide rather than workspace-scoped (for example domain availability and mailbox username availability) ignore the header. Workspace UIDs come from the workspaces endpoints or the `list_workspaces` MCP tool.

An API key carries the full permissions of the account that created it. There are no per-key scopes today; treat the key like a password, keep it server-side, and never embed it in a client or an agent prompt.

## MCP server: OAuth 2.1

The MCP server is a standard OAuth 2.1 protected resource. Discovery metadata is published at:

- `https://mcp.inboxkit.com/.well-known/oauth-authorization-server`
- `https://mcp.inboxkit.com/.well-known/oauth-protected-resource`

What the metadata declares:

- Authorization endpoint `https://mcp.inboxkit.com/authorize`, token endpoint `https://mcp.inboxkit.com/token`, revocation endpoint `https://mcp.inboxkit.com/revoke`.
- Grant types `authorization_code` and `refresh_token`; PKCE with `S256` is required.
- Dynamic client registration at `https://mcp.inboxkit.com/register`, so an MCP client can register itself without a pre-shared client ID.
- One scope, `all`, which grants the same permissions the signed-in user has.

A compliant MCP client (Claude, Cursor, or any client that follows the MCP authorization specification) handles the whole flow: it registers, opens the authorization URL for the user to approve, exchanges the code with PKCE, and attaches the resulting access token as `Authorization: Bearer <token>` on every MCP request. An unauthenticated request gets `401` with `WWW-Authenticate: Bearer error="invalid_token"`.

## Tokens, expiry, refresh and revocation

- REST API keys do not expire. Revoke and re-create them from **Settings, then API** if one leaks; the old key stops working immediately.
- MCP access tokens expire. Use the refresh token from the token response to obtain a new one; if the refresh fails, restart the authorization flow.
- Revoking a user's MCP authorization at `https://mcp.inboxkit.com/revoke`, or removing the user from the workspace, invalidates that client's tokens.
- A `401` means the credential is missing, expired or revoked. A `403` means the credential is valid but the account or workspace does not permit the action.

## Rate limits and costs

- Rate limits are enforced per API key and per MCP client. When a limit is hit the API returns `429`; back off and retry with jitter. Published limits are documented at https://docs.inboxkit.com.
- Reads are free. Actions that register domains, buy or pre-warm mailboxes, add warmup, enable InfraGuard or run inbox placement tests charge the workspace wallet or the card on file. The MCP server marks these tools `[PAID]` and requires an explicit `confirm: true` argument; agents must obtain the account owner's confirmation before setting it.
- Destructive actions (cancelling mailboxes, deleting workspaces, removing domains, wiping DNS records, disconnecting Cloudflare domains) are marked `[DESTRUCTIVE]` and carry the same `confirm` requirement.

## Support

Email support@inboxkit.com, or use the in-app chat. Please never send an API key or access token in a support message.