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"

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

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:

{
  "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:

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"