Book a demo

provision_sandbox

Provision a sandbox

act entity tenant-private since 2026-10-01

Creates a public sandbox for anybody, signed in or not: a test-mode-only org with sample yards and containers and no live data, and one sk_test_ API key that reaches it. Both expire 14 days later, when the sandbox is purged. The answer carries the whole key in `secret` once: a retry with the same Idempotency-Key answers the same sandbox with `secret` null. Limited to a few sandboxes per client a day, and a ceiling for everybody an hour; past a limit the call is refused with 429 and creates nothing. Every answer names the sandbox, which is how a Trade HQ contact finds it to keep it as a company's account.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: anyone (anybody, signed in or not, on the dispatcher's anonymous path; limited by what the call creates); a deactivated caller is refused first
idempotency
keyed
emits
sandbox.provisioned
MCP tool
none
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/provision_sandbox

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

No inputs.

Response

  • sandbox_id · string · The sandbox: the test-mode org the key reaches.
  • key_id · string · The key's id, its public part.
  • display · string · The key's prefix and id, safe to show anywhere. Never the secret.
  • secret · stringnull · The whole sk_test_ key, on the call that made the sandbox and never again: it is stored nowhere, so a replay answers null.
  • mode · string · Always test: the key never reaches live data.
  • expires_at · string · When the sandbox and its key stop and the sandbox is purged.
  • lifetime_days · integer · How long a sandbox lives: 14.
  • name · string · The sandbox's name, "Trade HQ sandbox" and six characters. Not a secret: give it to a Trade HQ contact to keep the sandbox as a company's account (TRA-474).
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The sandbox: the test-mode org the key reaches.",
      "x-data-class": "operational"
    },
    "key_id": {
      "type": "string",
      "description": "The key's id, its public part.",
      "x-data-class": "operational"
    },
    "display": {
      "type": "string",
      "description": "The key's prefix and id, safe to show anywhere. Never the secret.",
      "x-data-class": "operational"
    },
    "secret": {
      "type": [
        "string",
        "null"
      ],
      "description": "The whole sk_test_ key, on the call that made the sandbox and never again: it is stored nowhere, so a replay answers null.",
      "x-data-class": "operational"
    },
    "mode": {
      "type": "string",
      "enum": [
        "test"
      ],
      "description": "Always test: the key never reaches live data.",
      "x-data-class": "operational"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the sandbox and its key stop and the sandbox is purged.",
      "x-data-class": "operational"
    },
    "lifetime_days": {
      "type": "integer",
      "description": "How long a sandbox lives: 14.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "The sandbox's name, \"Trade HQ sandbox\" and six characters. Not a secret: give it to a Trade HQ contact to keep the sandbox as a company's account (TRA-474).",
      "x-data-class": "operational"
    }
  },
  "required": [
    "sandbox_id",
    "key_id",
    "display",
    "secret",
    "mode",
    "expires_at",
    "lifetime_days",
    "name"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileD5
APIF
MCPN
VoiceN
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: an MCP session is signed in, and the answer carries a secret, which is never handed to an agent
  • Voice: the answer carries a secret, which is never read aloud
  • OneBox: no document originates a sandbox
  • Outbound: crosses to no counterparty

Events

Related

None.