Authentication

All Cells API endpoints require authentication. Two methods are supported: an API key header and a Bearer token. Most integrations use the API key.

API key (recommended)

Pass your project API key in the x-api-key header on every request. API keys are scoped to a project and can be created or revoked from the Cells console at any time.

curl

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22"}'
curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22"}'

Warning

Treat your API key like a password. Never commit it to source control or expose it in client-side code. Use environment variables.

Bearer token

Authenticated users can pass a bearer token from a Mudbase user session as an alternative to an API key. This is primarily used for the Cells web console and CLI.

curl

curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22"}'
curl -X POST https://api.mudbase.dev/api/sandboxes/projects/YOUR_PROJECT_ID \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"language":"node","languageVersion":"22"}'

Gateway tokens

When you create a session, the response includes a short-lived token valid for 60 seconds. This token is used for direct gateway connections (WebSocket exec). If you need a fresh token for an existing session (for example, in the CLI), call the POST /sessions/:sessionId/connect-token endpoint with your API key.

Error responses

A missing or invalid credential returns 401 Unauthorized. An API key with insufficient project access returns 403 Forbidden.