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 and click New token. Give it a descriptive name like production-backend or ci-pipeline.

You can also create tokens via the API:

$
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:

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

1
import { ModboxClient } from "modbox-sdk";
2
3
const client = new ModboxClient({
4
  token: process.env.MODBOX_API_TOKEN,
5
});

Revoke a token

$
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

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

Response:

1
{
2
  "success": true,
3
  "tokens": {
4
    "access_token": "eyJ...",
5
    "refresh_token": "eyJ...",
6
    "expires_in": 300,
7
    "refresh_expires_in": 1800
8
  }
9
}

Refresh

Access tokens expire after 5 minutes. Refresh them with:

$
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:

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