---
title: "Open a session on an instance"
method: POST
path: "/sandboxes/{sandbox_id}/session"
tags: ["Sandboxes"]
---

# Open a session on an instance

`POST /sandboxes/{sandbox_id}/session`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/sandboxes/{sandbox_id}/session`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

A short-lived session JWT for one instance of an `active` sandbox,
to open `Logs` streams on the broker at `broker_url`; `PortForward` too
when the key holds `sandboxes:write`, and `Exec` and `Invoke` when it
holds `sandboxes:exec`. Mint a new one for each stream opened after
`expires_at`.

## Path parameters

- `sandbox_id` string, required: The sandbox's id (`sandbox_<uuid>`).

## Query parameters

- `replica` integer: The instance's replica number, from 0.

## Response `200`

Successful Response

- SandboxSession: A session JWT for one instance's streams on the broker: `Logs` always, `PortForward` when the calling key holds `sandboxes:write`, `Exec` and `Invoke` when it holds `sandboxes:exec`.
  - `token` string, required: The session JWT.
  - `broker_url` string, required: The broker to open streams on with `token`, as `host:port`.
  - `expires_at` string, date-time, required: When the broker stops accepting `token` for a new stream. A stream already open keeps running.
  - `replica` integer, required: The replica the session is bound to.

## Other responses

- `400`: Invalid or failed-validation request. `FAILED_PRECONDITION`: the sandbox is not `active`, or the instance at `replica` has stopped. `INVALID_ARGUMENT` on `replica`: the sandbox has no instance at it.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `429`: Rate limit exceeded.
- `500`: Internal error.
- `503`: Sandbox sessions are not available now, or sandboxes are still being set up for your workspace; retry shortly.

## Changes

- **2026-10-23** `e733493214f4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedra-labs/apis/hedra-api/changes/sandboxes/:sandbox_id/session/post.md)

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)