Skip to main content
POST
Mint a token for a private preview port

Authorizations

X-API-Key
string
header
required

Path Parameters

sandbox_id
string
required

The unique identifier of the sandbox. Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.

Pattern: ^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
port
integer
required

Published sandbox port. Port 49983 is reserved for Superserve's sandbox service.

Required range: 1024 <= x <= 65535

Body

application/json

Optional expiry for a preview token, independent of whether it is sent by header, used in a signed link, or stored by the edge in a browser cookie. Omit the body (or send {}) for a credential that remains valid until its generation changes.

expires_in_seconds
integer<int64>

Lifetime in whole seconds; omitted means no time expiry.

Required range: 1 <= x <= 604800

Response

Fresh header and signed-link credential; never cache this response

A single port-scoped credential with two explicit carriers. Machine clients normally send token in the request header named by header. For browser navigation, append the URL-encoded token under the parameter named by query_param, for example https://{port}-{sandbox_id}.<sandbox-domain>/?{query_param}={token}.

For an ordinary GET, the edge validates the signed link, sets the host-only __Host-superserve_preview_token cookie with Secure, HttpOnly, SameSite=None, Partitioned, Path=/, and no Domain, then returns a 302 to a same-origin HTTPS URL with every reserved token parameter removed. Unrelated query data is preserved. The redirect is Cache-Control: no-store with Referrer-Policy: no-referrer.

Non-GET requests and genuine WebSocket upgrade handshakes accept the query token directly without a redirect. In every case, the reserved header, query parameter, and cookie are removed before the upstream application receives the request. The edge revalidates cookie tokens on every request, so token expiry, generation rotation, access-mode change, or unpublication invalidates an existing browser session immediately; the browser may retain the now-unusable cookie value.

token
string
required

Secret token scoped to this sandbox, port, and generation. Send it using the request header named by header, or URL-encode it under the signed-link query parameter named by query_param.

port
integer
required
Required range: 1024 <= x <= 65535
header
string
required

Request-header name to use when sending token.

Example:

"X-Superserve-Preview-Token"

query_param
string
required

Query-parameter name to use when constructing a signed link.

Example:

"superserve_preview_token"

access
enum<string>
required

The published port's access mode.

Available options:
private
preview_access
enum<string>
required

Sandbox default for newly published ports.

Available options:
legacy_public,
public,
private
token_version
integer<int64>
required

Exact generation embedded in token.

Required range: x >= 1
expires_at
string<date-time>

Present only when expires_in_seconds was supplied. After this instant the token is rejected in every carrier, including an already-established browser cookie.