> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# Authentication

The Modbox API uses **Bearer tokens** for authentication. Every request must include an `Authorization` header.

## API Tokens (recommended)

API tokens are long-lived credentials ideal for server-to-server communication, CI/CD pipelines, and integrating Modbox into your backend.

### Create a token

Go to **Settings → API Tokens** in the [Modbox dashboard](https://app.modbox.run) and click **New token**. Give it a descriptive name like `production-backend` or `ci-pipeline`.

You can also create tokens via the API:

```bash
curl -X POST https://api.modbox.run/api-tokens/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "production-backend"}'
```

### Use the token

Include the token in every request:

```bash
curl https://api.modbox.run/sandboxes \
  -H "Authorization: Bearer mbx_your_api_token_here"
```

```typescript
import { ModboxClient } from "modbox-sdk";

const client = new ModboxClient({
  token: process.env.MODBOX_API_TOKEN,
});
```

```python
from modbox import ModboxClient
import os

client = ModboxClient(token=os.environ["MODBOX_API_TOKEN"])
```

### Revoke a token

```bash
curl -X DELETE https://api.modbox.run/api-tokens/mbx_your_token \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

***

## JWT Tokens (interactive sessions)

When users log in via the dashboard or your app, they receive short-lived JWT access tokens. Use these for user-facing flows.

### Login

```bash
curl -X POST https://api.modbox.run/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "you@example.com",
    "password": "yourpassword",
    "recaptchaToken": "..."
  }'
```

Response:

```json
{
  "success": true,
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "expires_in": 300,
    "refresh_expires_in": 1800
  }
}
```

### Refresh

Access tokens expire after 5 minutes. Refresh them with:

```bash
curl -X POST https://api.modbox.run/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'
```

***

## SSO (Google, GitHub, Microsoft)

Redirect users to the SSO login flow:

```
GET https://api.modbox.run/auth/sso/google
GET https://api.modbox.run/auth/sso/github
GET https://api.modbox.run/auth/sso/microsoft
```

After authentication, users are redirected to your app with tokens in the URL fragment.

***

## Workspace header

When making requests that are scoped to a workspace, include the `X-Workspace-Id` header:

```bash
curl https://api.modbox.run/sandboxes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: your-workspace-uuid"
```

You can find your workspace ID in the dashboard URL or via `GET /workspaces`.