Handle CORS on Blaxel

​

How Blaxel handles CORS

• Preflight (OPTIONS) requests are answered by Blaxel directly. They never reach your application, and they do not require authentication, even on a private preview.
• Normal responses come from your application. Blaxel adds CORS headers only when your application does not set them.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
Access-Control-Allow-Headers: Content-Type, Authorization, X-Blaxel-Preview-Token
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 86400
Access-Control-Expose-Headers: X-Blaxel-Source, X-Blaxel-Error-Code, X-Blaxel-Dispatch-State, Retry-After

• your frontend sends other request headers
• your frontend sends credentials (fetch(..., { credentials: "include" })), because browsers reject Access-Control-Allow-Origin: * on credentialed requests

​

Configure CORS headers on a preview

• Set Access-Control-Allow-Origin to your frontend’s exact origin (scheme, host and port, without a trailing slash).
• List every request header your frontend sends in Access-Control-Allow-Headers. Your value replaces the default list, so add X-Blaxel-Preview-Token back if your frontend sends it.
• Omit Access-Control-Allow-Credentials, because Blaxel already adds Access-Control-Allow-Credentials: true.

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const preview = await sandbox.previews.create({
  metadata: { name: "app" },
  spec: {
    port: 3000,
    public: false,
    responseHeaders: {
      "Access-Control-Allow-Origin": "https://app.example.com",
      "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Your-Header",
    },
  },
});
console.log(preview.spec.url);

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")
preview = await sandbox.previews.create({
    "metadata": {"name": "app"},
    "spec": {
        "port": 3000,
        "public": False,
        "responseHeaders": {
            "Access-Control-Allow-Origin": "https://app.example.com",
            "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Your-Header",
        },
    },
})
print(preview.spec.url)

# To update an existing preview, send a `PUT` request with the full spec: `port`, `public` and `responseHeaders`. Changes apply within a few seconds.
curl -X PUT "https://api.blaxel.ai/v0/sandboxes/my-sandbox/previews/app" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"name": "app"},
    "spec": {
      "port": 3000,
      "public": false,
      "responseHeaders": {
        "Access-Control-Allow-Origin": "https://app.example.com",
        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Your-Header"
      }
    }
  }'

​

Handle CORS in your application

​

Send credentials to a private preview

​

Check your CORS configuration

PREVIEW_URL="https://<id>.preview.bl.run"   # from preview.spec.url
ORIGIN="https://app.example.com"

curl -si -X OPTIONS "$PREVIEW_URL/api/anything" \
  -H "Origin: $ORIGIN" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type,x-your-header" \
  | grep -i '^access-control'

curl -si "$PREVIEW_URL/api/anything" \
  -H "Origin: $ORIGIN" \
  -H "X-Blaxel-Preview-Token: $PREVIEW_TOKEN" \
  | grep -i '^access-control-allow-origin'

await fetch("<PREVIEW_URL>/api/anything", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json", "X-Your-Header": "1" },
  body: "{}",
}).then(r => r.status);

​

Limitations

• One origin per preview. Preflight headers are static, so a preview allows a single origin for credentialed requests. To allow several origins (for example staging and production), create one preview per origin.
• Static header list. Every request header your frontend sends must be listed in Access-Control-Allow-Headers.
• Preflight cache. Browsers cache preflights for up to 24 hours (Access-Control-Max-Age: 86400). After changing the headers, hard-reload the page or test in a new private window.