Sandbox access tokens

A sandbox owner can create one access token for a sandbox and give it to a worker or another client. The token starts with skp_sb_ and is sent in the X-Api-Key header. It can operate only the sandbox it belongs to; it does not grant access to the owner's account or other sandboxes.

Use the owner's API key for every token management request below. A sandbox access token cannot create, inspect, rotate, or disable itself.

Create and use a token

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

The response contains the plaintext token only once:

{
  "status": "success",
  "data": {
    "token": "skp_sb_...",
    "enabled": true,
    "created_at": "2026-09-18T12:00:00Z"
  }
}

Store the token securely and pass it to the client that operates this sandbox. For example:

curl -X POST "https://api.sb.createos.sh/v1/sandboxes/$SANDBOX_ID/exec" \
  -H "X-Api-Key: $SANDBOX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"echo","args":["hello"]}'

Do not put a sandbox access token in X-Access-Token, X-Auth-Token, or a URL query parameter.

Scope

Allowed on the bound sandbox	Requires the owner's API key
Get status; run and stream commands; transfer files; use managed processes, PTYs, shell and tunnels; use computer APIs; read metrics and bandwidth; pause, resume, or destroy the sandbox.	Create or list sandboxes; fork; manage access tokens, networks, disks, templates, devices, ingress, egress, SSH keys, size, or bandwidth quota; use account and billing APIs.

A request for another sandbox returns 404. A disallowed operation on the bound sandbox returns 403.

Manage the token

All four endpoints use https://api.sb.createos.sh and require X-Api-Key: $CREATEOS_API_KEY.

Action	Method and path	Result
Create	`POST /v1/sandboxes/{id}/access-token`	Returns the plaintext token once. Returns `409` if a token is already enabled or the sandbox lifecycle blocks creation.
Inspect	`GET /v1/sandboxes/{id}/access-token`	Returns `enabled`, a redacted `token_hint`, `created_at`, and `rotated_at` when present. Never returns the plaintext. If no token exists, returns `{"enabled":false}`.
Rotate	`POST /v1/sandboxes/{id}/access-token/rotate`	Replaces the token and returns the new plaintext once. Returns `404` if no token exists; create one first. Returns `409` if the sandbox lifecycle blocks rotation.
Disable	`DELETE /v1/sandboxes/{id}/access-token`	Returns `{"enabled":false}`. Repeating the request is safe.

For example, rotate a token with the owner's key and replace the worker's stored credential with the new data.token:

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

Rotation invalidates the old token. Disable and rotation take effect immediately in the sandbox's home region; propagation to other regions is asynchronous.

See Authentication for the other supported credential types. For a complete delegation workflow, follow Delegate access to one sandbox.