How-to: delegate access to one sandbox

Give a worker control of one sandbox without sharing your account API key. The owner creates and manages a sandbox access token through the REST API; the worker can use the token with the TypeScript SDK as its apiKey.

You need an existing sandbox ID and an owner API key from the CreateOS dashboard. Keep the owner key out of the worker's environment.

1. Create the token as the owner

export SANDBOX_ID="sb-..."
 
curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/access-token" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Save the returned data.token securely as SANDBOX_ACCESS_TOKEN in the worker's secret store. It is shown only when created or rotated. The token begins with skp_sb_. Only one token can be enabled for a sandbox; a second create returns 409, so rotate the existing token when replacing it.

2. Connect from the worker

import { Sandbox } from "@nodeops-createos/sandbox";
 
const id = process.env.SANDBOX_ID;
const token = process.env.SANDBOX_ACCESS_TOKEN;
if (!id || !token) throw new Error("Set SANDBOX_ID and SANDBOX_ACCESS_TOKEN");
 
const sandbox = await Sandbox.connect(id, { apiKey: token });
const output = await sandbox.runCommand("echo", ["hello"]);
console.log(output.result.stdout);

The SDK sends this credential as X-Api-Key. Use the token only for operations on its bound sandbox: inspect status, execute commands, transfer files, use managed processes or computer APIs, read metrics, pause, resume, or destroy it. The worker cannot create or list sandboxes, change the sandbox's network or security settings, manage billing, or manage access tokens.

Requests for another sandbox return 404; operations outside the token's scope return 403. Do not send the token in a URL or in the X-Access-Token or X-Auth-Token headers.

3. Rotate or disable access

Use the owner's API key to replace the worker's token:

curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/access-token/rotate" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Save the new data.token in the worker's secret store. The old token stops working after rotation. Rotation returns 404 if no token exists; create one first.

To check whether a token is enabled without revealing it, inspect its redacted hint:

curl "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/access-token" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

To revoke the worker's access:

curl -X DELETE "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/access-token" \
  -H "X-Api-Key: $CREATEOS_API_KEY"

Disabling a token is safe to repeat. Rotation and disable take effect immediately in the sandbox's home region and propagate asynchronously to other regions.

See the REST API reference for all endpoint responses and errors. For a runnable SDK workflow using createAccessToken(), withAccessToken(), rotation, and revocation, see example 57 in the examples catalog.