Mint a token for a private preview port
Activates token authentication for an already-published private port
and returns a credential scoped to exactly this sandbox, port, and
token generation. A machine client sends the response’s token value
in a request header whose name is the response’s header value.
For browser navigation, construct a signed URL by adding the URL-encoded
token under the query-parameter name returned in query_param. An
ordinary GET exchanges a valid query token for a secure host-only
cookie and returns a 302 redirect to the same-origin HTTPS URL with
the credential removed. The bootstrap response is Cache-Control: no-store and Referrer-Policy: no-referrer. Non-GET requests and
complete WebSocket upgrade handshakes authenticate a valid query token
directly because they cannot round-trip that redirect. The edge strips
all preview-token header, query, and cookie carriers before forwarding
any request to sandbox code.
Public or unpublished ports cannot mint credentials. Minting requires sandbox write access; an incapable or stale host is rejected rather than activating a policy it cannot enforce.
The request body is optional. Omit it (or send {}) for a token that
remains valid until rotation, access-mode change, or unpublication.
An explicit expiry is also enforced for a cookie bootstrapped from that
token, even if the browser still stores the cookie.
Authorizations
Path Parameters
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.
^(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}$Published sandbox port. Port 49983 is reserved for Superserve's sandbox service.
1024 <= x <= 65535Body
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.
Lifetime in whole seconds; omitted means no time expiry.
1 <= x <= 604800Response
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.
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.
1024 <= x <= 65535Request-header name to use when sending token.
"X-Superserve-Preview-Token"
Query-parameter name to use when constructing a signed link.
"superserve_preview_token"
The published port's access mode.
private Sandbox default for newly published ports.
legacy_public, public, private Exact generation embedded in token.
x >= 1Present only when expires_in_seconds was supplied. After this
instant the token is rejected in every carrier, including an
already-established browser cookie.