auth.md

​

Protected resources

​

Step 1: Discover

• The MCP server answers 401 with WWW-Authenticate: Bearer realm="Blaxel MCP", resource_metadata="...". Follow it.
• The Blaxel API answers 401 with {"code":401,"error":"Unauthorized"} and no WWW-Authenticate header. Come back to this file.
• https://api.blaxel.ai/.well-known/oauth-protected-resource describes the MCP server (resource is https://api.blaxel.ai/v0/mcp). The Blaxel API has no protected resource metadata of its own yet.
• The metadata only advertises the openid, email, profile and offline_access scopes. Access follows the role of the user or service account in each workspace, not the token scope.
• The CLI device login and the client credentials grant are not advertised in the metadata. Use them as described below.

​

Step 2: Pick a method

1. You can run the Blaxel CLI and a human can open a URL: use CLI login.
2. You are an MCP client: use MCP OAuth.
3. You run unattended (CI, backend, scheduled job) and a workspace admin created a service account for you: use service account client credentials.
4. None of the above: use the API key fallback.

​

Step 3: Get a credential

​

CLI login

bl login my-workspace

• The user confirms the login in a browser. The CLI waits about 3 minutes for that confirmation.
• Without a terminal (for example when a coding agent runs the command), bl login asks nothing. It prints the login URL on its own line and how long it waits. Show that URL to the user and wait for the command to exit. This needs CLI version 0.1.123 or later.
• Without a workspace argument, bl login picks the current workspace if the login can use it, or else the first workspace by name, and says which one.
• With a workspace argument, bl login uses BL_CLIENT_CREDENTIALS or BL_API_KEY when one is set.
• The CLI saves the credential in its local configuration and refreshes it. The Blaxel SDKs reuse it. bl token prints a current access token.
• The login token reaches every workspace of the user. Select one per request (see Step 4).

​

MCP OAuth

​

Service account client credentials

curl -X POST https://api.blaxel.ai/v0/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{"grant_type":"client_credentials","client_id":"'"$CLIENT_ID"'","client_secret":"'"$CLIENT_SECRET"'"}'

• The token is valid for 2 hours. Request a new one when it expires. There is no refresh token.
• The token only works in the service account’s workspace, with the service account’s role.
• The CLI and SDKs read the same credentials from BL_CLIENT_CREDENTIALS, set to the base64 encoding of client_id:client_secret, with BL_WORKSPACE.

​

API key fallback

export BL_WORKSPACE=my-workspace
export BL_API_KEY=...

• An API key never expires unless an expiry was set when it was created.
• A personal API key reaches every workspace of its user. Prefer a service account key, which only reaches one workspace.
• The bl CLI reads BL_WORKSPACE and BL_API_KEY directly, so bl login is not needed.

​

Step 4: Call the API

GET /v0/sandboxes HTTP/1.1
Host: api.blaxel.ai
Authorization: Bearer <access token or API key>
X-Blaxel-Workspace: my-workspace

• X-Blaxel-Authorization: Bearer ... is accepted in place of Authorization.
• Send X-Blaxel-Workspace when the identity belongs to more than one workspace. Without it, those requests fail with 400.

​

Step 5: Create a sandbox

curl -X POST https://api.blaxel.ai/v0/sandboxes \
  -H "Authorization: Bearer $BL_API_KEY" -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{"name":"my-sandbox"},"spec":{"runtime":{"image":"blaxel/base-image:latest","memory":2048}}}'
# then, with metadata.url from the response:
curl -X POST "$SANDBOX_URL/process" -H "Authorization: Bearer $BL_API_KEY" \
  -H 'Content-Type: application/json' -d '{"command":"echo hello","waitForCompletion":true}'

​

Errors

​

Revocation

• There is no token revocation endpoint. Access tokens expire after 2 hours.
• Users delete their API keys in the Blaxel console. Workspace admins delete service account keys and service accounts.
• bl logout removes the credential saved by the CLI. It does not revoke tokens on the server.

​

Not supported

• agentic registration (/agent/identity), including anonymous registration
• verified-email claim ceremonies (service_auth)
• ID-JAG identity assertions and the JWT-bearer grant
• token exchange
• revocation events (Security Event Tokens)
• issuing a credential to an agent before a human signs in to Blaxel or a workspace admin creates it