Sandboxes

Rotate a private preview port's token generation

Advances only this published private port’s token generation, revoking every older token for it while leaving sibling ports unchanged. The revocation is committed even if the current host cannot deliver or enforce the replacement; in that case the request returns an error and no credential. Rotation requires sandbox write access. A successful response contains a fresh non-expiring token for the new generation and identifies both its header and signed-link query carriers. Rotation immediately makes older browser cookies unusable because every request revalidates the cookie’s embedded generation.

POST

sandboxes

{sandbox_id}

preview-ports

{port}

token

rotate

Rotate a private preview port's token generation

curl --request POST \
  --url https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate"

headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "token": "<string>",
  "port": 33279,
  "header": "X-Superserve-Preview-Token",
  "query_param": "superserve_preview_token",
  "access": "private",
  "token_version": 2,
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

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

Response

Fresh header and signed-link credential for the new generation; 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.

Mint a token for a private preview port

Run a command and wait for it to finish

Rotate a private preview port's token generation

curl --request POST \
  --url https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate"

headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}/preview-ports/{port}/token/rotate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "token": "<string>",
  "port": 33279,
  "header": "X-Superserve-Preview-Token",
  "query_param": "superserve_preview_token",
  "access": "private",
  "token_version": 2,
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Sandboxes

Exec

Files

Templates

Secrets

Billing

Team Management

Activity

Rotate a private preview port's token generation

Authorizations

Path Parameters

Response