> ## Documentation Index > Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a secret > Stores a credential under the caller's team. The plaintext is envelope-encrypted at rest and is never returned by any API. At sandbox-create time, bind the secret to an environment-variable name via the `secrets` map on `POST /sandboxes`; the agent sees a proxy token in env and the in-host enforcement daemon swaps it for the real value at egress. Use `provider` for built-in shortcuts (e.g. `anthropic`, `openai`, `github`, `stripe`) which auto-fill the auth scheme and allowed upstream hosts. Use `auth` + `hosts` for a custom integration. ## OpenAPI ````yaml https://raw.githubusercontent.com/superserve-ai/sandbox/refs/heads/main/api/openapi.yaml post /secrets openapi: 3.1.0 info: title: Superserve API version: 0.1.0 description: > Superserve provides sandbox infrastructure to run AI agents in the cloud. Powered by Firecracker MicroVMs. ## Sandbox lifecycle ``` active <--> paused --> deleted ``` A sandbox is `active` when running and `paused` after being paused. Resuming a paused sandbox returns it to `active`. Deleting releases all resources. | Endpoint | What it does | |----------|-------------| | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) | | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network rules) | | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM | | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it left off | | `DELETE /sandboxes/:id` | Delete sandbox and all resources | ## Sandbox environment By default sandboxes boot from the curated `superserve/base` template (Ubuntu 24.04, 1 vCPU, 1 GB RAM, 4 GB disk, with Python 3.12, Node.js 22, npm, git, curl, and build-essential pre-installed). Callers can override with any template name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned template UUID via the `from_template` field on `POST /sandboxes`. ## Files and commands `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use its `X-Access-Token` (returned by create, resume, and activate), not the team API key. Two host forms reach them: - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id: `. - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header needed. contact: name: Superserve Team license: name: Proprietary servers: - url: https://api.superserve.ai description: Production security: [] paths: /secrets: post: tags: - Secrets summary: Create a secret description: | Stores a credential under the caller's team. The plaintext is envelope-encrypted at rest and is never returned by any API. At sandbox-create time, bind the secret to an environment-variable name via the `secrets` map on `POST /sandboxes`; the agent sees a proxy token in env and the in-host enforcement daemon swaps it for the real value at egress. Use `provider` for built-in shortcuts (e.g. `anthropic`, `openai`, `github`, `stripe`) which auto-fill the auth scheme and allowed upstream hosts. Use `auth` + `hosts` for a custom integration. operationId: createSecret requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSecretRequest' responses: '201': description: Secret created content: application/json: schema: $ref: '#/components/schemas/SecretResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' security: - apiKey: [] components: schemas: CreateSecretRequest: type: object required: - name - value properties: name: type: string maxLength: 128 pattern: ^[A-Za-z_][A-Za-z0-9_-]*$ description: > Identifier used to reference the secret later (e.g. in the `secrets` map on `POST /sandboxes`). value: type: string maxLength: 8192 description: Cleartext credential. Encrypted at rest; never returned. provider: type: string description: > Built-in provider shortcut (e.g. `anthropic`, `openai`, `github`, `stripe`). When set, auto-fills auth scheme and allowed upstream hosts. Mutually exclusive with `auth` and `hosts`. `github` emits a `per_host` config so the same PAT works for both api.github.com REST (`Bearer`) and github.com git over HTTPS (`Basic` with `x-access-token`). auth: $ref: '#/components/schemas/SecretAuthConfig' hosts: type: array items: type: string maxItems: 16 description: > Upstream allow list. Required when `auth` is set. Each entry is a hostname or single-level wildcard (e.g. `api.example.com`, `*.example.com`). SecretResponse: type: object required: - id - name - auth_type - auth_config - hosts - created_at - updated_at properties: id: type: string format: uuid name: type: string auth_type: type: string enum: - bearer - basic - api-key - custom - per_host description: > `per_host` indicates a multi-rule secret; the resolved rules are in `auth_config.per_host`. auth_config: type: object additionalProperties: true description: Resolved auth scheme details (no cleartext value). provider_shortcut: type: string nullable: true description: Provider shortcut used at creation, if any. hosts: type: array items: type: string created_at: type: string format: date-time updated_at: type: string format: date-time last_used_at: type: string format: date-time nullable: true description: Timestamp of the most recent egress that used this secret. SecretAuthConfig: description: | Egress auth shape. Use the single-rule form (`type` + type-specific fields) for credentials that authenticate the same way on every host. Use `per_host` when the same credential needs different auth schemes on different hosts of the same provider — for example one host accepts `Bearer` while another accepts `Basic` with a fixed username. Single-rule and `per_host` are mutually exclusive. oneOf: - $ref: '#/components/schemas/SecretAuthConfigSingleRule' - $ref: '#/components/schemas/SecretAuthConfigPerHost' Error: type: object description: | Error envelope. `error.code` is a stable, machine-readable identifier (e.g. `bad_request`, `not_found`, `conflict`, `rate_limited`, `too_many_builds`, `too_many_templates`, `too_many_sandboxes`, `image_pull_failed`, `step_failed`, `snapshot_failed`, `start_cmd_failed`, `ready_cmd_failed`, `build_failed`). `error.message` is human-readable and may change between releases; clients should branch on `code`, not `message`. properties: error: type: object properties: code: type: string message: type: string SecretAuthConfigSingleRule: type: object required: - type properties: type: type: string enum: - bearer - basic - api-key - custom description: | Egress auth scheme: - `bearer`: `Authorization: Bearer ` - `basic`: `Authorization: Basic ` - `api-key`: custom header (set `header`, optionally `prefix`) - `custom`: caller-defined `headers` map header: type: string description: Header name (required for `api-key`). prefix: type: string description: Optional value prefix (used by `api-key`). username: type: string description: > Optional username for `basic`. When set, this username is used verbatim in the outbound Basic header (overrides any username sent by the client). When empty, the inbound username is preserved, or `x` is used if absent. headers: type: object additionalProperties: type: string maxProperties: 8 description: Header-name → value template (required for `custom`). SecretAuthConfigPerHost: type: object required: - per_host properties: per_host: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/SecretPerHostRule' description: > Per-host rule list. The daemon picks the first rule whose `hosts` match the upstream host at egress. Every host referenced here must also appear in the top-level `hosts` allowlist. Rules may not overlap (a host belongs to at most one rule). SecretPerHostRule: type: object required: - hosts - type properties: hosts: type: array minItems: 1 maxItems: 16 items: type: string description: > Hosts this rule authenticates. Exact hostnames or single-level wildcards (`*.example.com`). type: type: string enum: - bearer - basic - api-key - custom header: type: string description: Header name (required for `api-key`). prefix: type: string description: Optional value prefix (used by `api-key`). username: type: string description: >- Username slot for `basic`. Used verbatim in the outbound `Basic ` header. headers: type: object additionalProperties: type: string maxProperties: 8 description: Header-name → value template (required for `custom`). responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Operation conflicts with the resource's current state content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-API-Key ````