---
title: "A short-lived token a browser uses to reach this one sandbox directly."
method: POST
path: "/v1/sandboxes/{id}/sessions"
tags: ["sandboxes"]
---

# A short-lived token a browser uses to reach this one sandbox directly.

`POST /v1/sandboxes/{id}/sessions`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}/sessions`
- Auth: HTTP bearer

The token runs commands, reads and writes files and reaches previews in this sandbox only, and cannot stop, pause, extend, fork, snapshot or change it, create anything, or reach anything else. It acts as this key's agent and ends when this key is revoked. Lasts ttlSeconds (3600 unless asked, 60 to 86400). Needs a key that may run commands in the sandbox. The token is in this answer only.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `ttlSeconds` integer: How long it lasts, in seconds: an hour unless asked, a day at most.
  - `origins` string[]: The pages that may use it: exact origins, https://host[:port], or http://localhost[:port] while developing. The API answers CORS for these and refuses a request from any other page. Leave empty for a session used only outside a browser.
  - `name` string: Your own handle for it, such as the user it is for.

## Response `200`

Success

- object
  - `id` string, uuid
  - `sandboxId` string, uuid
  - `name` string, nullable
  - `origins` string[]
  - `createdBy` string: The agent whose key made it; the session acts as it.
  - `createdAt` string, date-time
  - `expiresAt` string, date-time
  - `revokedAt` string, date-time, nullable
  - `state` 'active' | 'expired' | 'revoked'
  - `token` string, nullable: The bearer token, shown once. Null when this answer replays an earlier create with the same Idempotency-Key: revoke that session and make a new one.
  - `apiUrl` string: Where the session is used: this API's origin.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)