> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirebox.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault Secrets

> List, create, read, update, and delete vault secrets. Payloads are ciphertext produced client-side.

Secrets are stored as ciphertext plus plaintext metadata (`name`, `type`,
`description`). Listing returns metadata only. Creating, updating, and deleting
are admin-only; reading is available to identity-scoped keys with `vault:read`
for the secrets they were granted.

### Secret Object

<ResponseField name="id" type="string">
  Secret identifier (`vsec_` prefix). Client-generated on create.
</ResponseField>

<ResponseField name="type" type="string">
  `login`, `api_key`, or `other`.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable label (plaintext). Secrets can be addressed by name in the SDK/CLI.
</ResponseField>

<ResponseField name="description" type="string | null">
  Optional note (plaintext).
</ResponseField>

<ResponseField name="encrypted_payload" type="string">
  Base64 AES-256-GCM ciphertext of the JSON payload. Returned by single-secret reads and unlock, not by list.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 update timestamp.
</ResponseField>

### Payload Shapes (plaintext, before encryption)

* **login** — `username`, `email`, `password`, `service_url`, and optional
  `totp` (`{ secret, algorithm, digits, period }`).
* **api\_key** — `key`, optional `service_url`.
* **other** — `data`.

### Operations

| Method & Path | Description |
| :- | :- |
| `GET /api/v1/vault/secrets` | List metadata. Optional `?type=` filter. |
| `POST /api/v1/vault/secrets` | Create. Body: `id`, `type`, `name`, `description?`, `encrypted_payload`. Admin only. |
| `GET /api/v1/vault/secrets/{id}` | Read one, including `encrypted_payload`. |
| `PATCH /api/v1/vault/secrets/{id}` | Update `name`, `description`, and/or `encrypted_payload`. Admin only. |
| `DELETE /api/v1/vault/secrets/{id}` | Delete (and its access grants). Admin only. |

<Note>
  An identity-scoped caller that requests a secret it was not granted receives
  `404`, so the API does not reveal that the secret exists.
</Note>

<RequestExample>
  ```python Python theme={null}
  import os
  from wirebox.vault import VaultSecretType, LoginPayload, parse_totp_uri

  vault = wb.vault.unlock(os.environ["WIREBOX_VAULT_KEY"])

  # Create (payload encrypted locally before upload)
  vault.create_secret(
      type=VaultSecretType.LOGIN,
      name="GitHub",
      payload=LoginPayload(
          username="eva",
          password="s3cr3t",
          totp=parse_totp_uri("otpauth://totp/GitHub:eva?secret=JBSWY3DPEHPK3PXP"),
      ),
  )

  # Read (by name or id) and update with the full payload
  login = vault.get_login("GitHub")
  login.password = "rotated"
  vault.update_secret("GitHub", payload=login)
  vault.delete_secret("GitHub")
  ```

  ```ts TypeScript theme={null}
  import { VaultSecretType, parseTotpUri } from "@wirebox-sh/sdk";

  const vault = await wb.vault.unlock(process.env.WIREBOX_VAULT_KEY);

  // Create (payload encrypted locally before upload)
  await vault.createSecret({
    type: VaultSecretType.LOGIN,
    name: "GitHub",
    payload: {
      username: "eva",
      password: "s3cr3t",
      totp: parseTotpUri("otpauth://totp/GitHub:eva?secret=JBSWY3DPEHPK3PXP"),
    },
  });

  // Read (by name or id) and update
  const login = vault.getLogin("GitHub");
  await vault.updateSecret("GitHub", { payload: { ...login, password: "rotated" } });
  await vault.deleteSecret("GitHub");
  ```

  ```bash CLI theme={null}
  wirebox vault list --type login
  wirebox vault add --type login --name GitHub --username eva --password
  wirebox vault get GitHub --reveal
  wirebox vault set GitHub --password
  wirebox vault rm GitHub
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "secrets": [
      {
        "id": "vsec_01J8ABC123XYZ",
        "type": "login",
        "name": "GitHub",
        "description": null,
        "created_at": "2026-10-10T10:00:00Z",
        "updated_at": "2026-10-10T10:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.