Secret - Superserve

Secret manages credentials Superserve attaches to outbound requests; Provider lists the built-in shortcuts. Python ships both sync (Secret, Provider) and async (AsyncSecret, AsyncProvider) variants with identical method names.

Import

import { Secret, Provider } from "@superserve/sdk"

from superserve import Secret, Provider
# Async variants:
from superserve import AsyncSecret, AsyncProvider

The SDK reads SUPERSERVE_API_KEY from the environment by default; pass apiKey / api_key to override.

Factory methods

`Secret.create`

Create a secret. Provide either a provider shortcut or a custom auth config with hosts — they’re mutually exclusive.

// Provider shortcut.
await Secret.create({ name: "openai-prod", value: key, provider: "openai" })

// Custom auth.
await Secret.create({
  name: "internal-api",
  value: token,
  hosts: ["api.internal.example.com"],
  auth: { type: "api-key", header: "X-Api-Key" },
})

Secret.create(name="openai-prod", value=key, provider="openai")

Secret.create(
    name="internal-api",
    value=token,
    hosts=["api.internal.example.com"],
    auth={"type": "api-key", "header": "X-Api-Key"},
)

Options:

Option	Type	Description
`name`	`string`	Required. Unique secret name.
`value`	`string`	Required. The credential. Encrypted on the platform; never returned.
`provider`	`string`	A built-in shortcut (see `Provider.list`). Mutually exclusive with `auth` / `hosts`.
`auth`	`SecretAuth`	Custom auth config. Requires `hosts`.
`hosts`	`string[]`	Upstream hosts the credential may authenticate. Required with `auth`.

Returns a Secret.

`Secret.get`

Fetch an existing secret by name. Returns a Secret.

const secret = await Secret.get("openai-prod")

secret = Secret.get("openai-prod")

`Secret.list`

List all secrets for the team. Returns an array of SecretInfo.

const secrets = await Secret.list()

secrets = Secret.list()

`Secret.deleteByName` / `Secret.delete_by_name`

Delete a secret by name. Idempotent. Revokes the secret everywhere immediately — bound stand-in tokens stop working.

await Secret.deleteByName("openai-prod")

Secret.delete_by_name("openai-prod")

Methods on `secret`

`rotate`

Replace the value. Bound sandboxes keep their env var; the new value is used on subsequent requests. Returns the updated Secret.

await secret.rotate(newValue)

secret.rotate(new_value)

`getAudit` / `get_audit`

Requests made with this secret, across all sandboxes, newest first. Returns an array of ProxyAuditEvent.

const events = await secret.getAudit({ limit: 50, status: "4xx" })

events = secret.get_audit(limit=50, status="4xx")

Option	Type	Description
`limit`	`number`	Max events to return.
`before`	`number`	Cursor — return events older than this event `id`.
`status`	`"2xx" \| "3xx" \| "4xx" \| "5xx" \| "errors"`	Filter by status class.

`getSandboxes` / `get_sandboxes`

Sandboxes this secret is currently bound to. Returns an array of SecretSandboxBinding.

const bindings = await secret.getSandboxes()

bindings = secret.get_sandboxes()

`getInfo` / `get_info` · `delete`

getInfo() re-fetches the latest SecretInfo; delete() removes this secret (idempotent).

`Provider.list`

List the built-in provider shortcuts. Returns an array of ProviderShortcut.

const providers = await Provider.list()

providers = Provider.list()

Types

`SecretInfo`

Field	Type
`id`	`string`
`name`	`string`
`authType` / `auth_type`	`"bearer" \| "basic" \| "api-key" \| "custom" \| "per_host"`
`authConfig` / `auth_config`	`Record<string, unknown>`
`providerShortcut` / `provider_shortcut`	`string \| undefined`
`hosts`	`string[]`
`createdAt` / `created_at`	`Date` / `datetime`
`updatedAt` / `updated_at`	`Date` / `datetime`
`lastUsedAt` / `last_used_at`	`Date \| undefined`

`ProviderShortcut`

Field	Type
`name`	`string` — pass as `provider` to `Secret.create`
`display`	`string`
`authType` / `auth_type`	`SecretAuthType`
`hosts`	`string[]`
`tokenShape` / `token_shape`	`string` — e.g. `"sk-ant-api03-..."`

`ProxyAuditEvent`

Field	Type
`id`	`number`
`ts`	`Date` / `datetime`
`sandboxId` / `sandbox_id`	`string`
`sandboxName` / `sandbox_name`	`string \| undefined`
`method` · `host` · `path`	`string`
`status`	`number`
`upstreamStatus` / `upstream_status`	`number \| undefined`
`latencyMs` / `latency_ms`	`number \| undefined`
`errorCode` / `error_code`	`string \| undefined`

`SecretSandboxBinding`

Field	Type
`sandboxId` / `sandbox_id`	`string`
`sandboxName` / `sandbox_name`	`string`
`envKey` / `env_key`	`string`
`status`	`SandboxStatus`

For the network log types (NetworkEvent, NetworkLogPage), see Sandbox.getNetworkLog.

​Import

​Factory methods

​Secret.create

​Secret.get

​Secret.list

​Secret.deleteByName / Secret.delete_by_name

​Methods on secret

​rotate

​getAudit / get_audit

​getSandboxes / get_sandboxes

​getInfo / get_info · delete

​Provider.list

​Types

​SecretInfo

​ProviderShortcut

​ProxyAuditEvent

​SecretSandboxBinding