> ## 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.

# Secret

> The Secret and Provider classes - factory methods, instance methods, and types for credential management.

`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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  import { Secret, Provider } from "@superserve/sdk"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  from superserve import Secret, Provider
  # Async variants:
  from superserve import AsyncSecret, AsyncProvider
  ```
</CodeGroup>

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.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  // 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" },
  })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  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"},
  )
  ```
</CodeGroup>

**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`](#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`.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const secret = await Secret.get("openai-prod")
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  secret = Secret.get("openai-prod")
  ```
</CodeGroup>

### `Secret.list`

List all secrets for the team. Returns an array of [`SecretInfo`](#secretinfo).

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const secrets = await Secret.list()
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  secrets = Secret.list()
  ```
</CodeGroup>

### `Secret.deleteByName` / `Secret.delete_by_name`

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

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  await Secret.deleteByName("openai-prod")
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  Secret.delete_by_name("openai-prod")
  ```
</CodeGroup>

## 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`.

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  await secret.rotate(newValue)
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  secret.rotate(new_value)
  ```
</CodeGroup>

### `getAudit` / `get_audit`

Requests made with this secret, across all sandboxes, newest first. Returns an array of [`ProxyAuditEvent`](#proxyauditevent).

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const events = await secret.getAudit({ limit: 50, status: "4xx" })
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  events = secret.get_audit(limit=50, status="4xx")
  ```
</CodeGroup>

| 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`](#secretsandboxbinding).

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const bindings = await secret.getSandboxes()
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  bindings = secret.get_sandboxes()
  ```
</CodeGroup>

### `getInfo` / `get_info` · `delete`

`getInfo()` re-fetches the latest [`SecretInfo`](#secretinfo); `delete()` removes this secret (idempotent).

## `Provider.list`

List the built-in provider shortcuts. Returns an array of [`ProviderShortcut`](#providershortcut).

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  const providers = await Provider.list()
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
  providers = Provider.list()
  ```
</CodeGroup>

## 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`](/sdk-reference/sandbox#getnetworklog-get-network-log).