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

# Customer-protected secrets

> Wrap secrets with your own key, so Hyperbrowser stores nothing it can decrypt on its own.

A customer-protected secret is a [secret](https://hyperbrowser.ai/docs/sandboxes/secrets.md) that is also wrapped with a key you hold. Hyperbrowser stores only the wrapped value, so it can't decrypt the secret without you. Each time you use the secret, the SDK unwraps it on your machine with your key and passes the result with the request. Only the platform can open what you pass, and only for the version you unwrapped.

You can use customer-protected secrets anywhere a sandbox takes secrets: in `exec`, in `processes.start` and in an image's startup command. You can also add them to [vaults](https://hyperbrowser.ai/docs/sandboxes/vaults.md) and use them as [1Password](https://hyperbrowser.ai/docs/sandboxes/1password.md) tokens. They can't be typed into browser pages.

> [!NOTE]
>
> Customer-protected secrets need Node SDK 1.5.0 or Python SDK 1.15.0. They're part of [Secrets](https://hyperbrowser.ai/docs/sandboxes/secrets.md) and use the same scopes. To read wrapped values, a restricted API key needs `secrets.use`, and it needs `secrets.manage` to rewrap them. The [CLI](https://hyperbrowser.ai/docs/sandboxes/cli.md) can list and inspect them, but it can't unwrap them or add versions.

## Create a key

Use an RSA key (2048 bits or more), an EC key (P-256, P-384 or P-521), or an X25519 or X448 key. For example:

```bash theme={null}
openssl genpkey -algorithm X25519 -out customer-key.pem
```

Keep the private key yourself. Hyperbrowser never receives it. The public key alone can create secrets and add versions, but using a secret needs the private key.

## Create a secret

Pass your key when you create the secret or add a version. The value is encrypted to the platform as usual, then wrapped with your key before it's uploaded.

```typescript Node.js theme={null}
import fs from "node:fs";
import { Hyperbrowser, createCustomerKey } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({ apiKey: process.env.HYPERBROWSER_API_KEY });
const customerKey = createCustomerKey(fs.readFileSync("customer-key.pem", "utf8"));

await client.secrets.create({ name: "db-pass", value: process.env.DB_PASS!, customerKey });

// Later, to rotate the value:
await client.secrets.addVersion("db-pass", process.env.NEW_DB_PASS!, { customerKey });
```

```python Python theme={null}
import os
from hyperbrowser import Hyperbrowser, create_customer_key

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])
customer_key = create_customer_key(open("customer-key.pem").read())

client.secrets.create({"name": "db-pass", "value": os.environ["DB_PASS"], "customer_key": customer_key})

# Later, to rotate the value:
client.secrets.add_version("db-pass", os.environ["NEW_DB_PASS"], customer_key=customer_key)
```

A secret's protection is set when it's created and can't change. The secret's details show `protection: "customer"`, and each version shows `outerKid`, the ID of the key that wrapped it. A key's ID is its RFC 7638 thumbprint unless you set one with `createCustomerKey(key, { kid })` or `create_customer_key(key, kid=...)`.

## Use it in a sandbox

Unwrap the secret and pass the result where you'd pass the secret's name. `unwrap` returns `{ name, version, unwrapped }`, pinned to the version it unwrapped, which is the latest unless you ask for another.

```typescript Node.js theme={null}
const dbPass = await client.secrets.unwrap("db-pass", customerKey);

const sandbox = await client.sandboxes.create({ imageName: "node" });
const result = await sandbox.exec("node migrate.js", { secrets: { DB_PASS: dbPass } });

const previous = await client.secrets.unwrap("db-pass", customerKey, { version: 1 });
```

```python Python theme={null}
db_pass = client.secrets.unwrap("db-pass", customer_key)

sandbox = client.sandboxes.create({"image_name": "node"})
result = sandbox.exec("node migrate.js", secrets={"DB_PASS": db_pass})

previous = client.secrets.unwrap("db-pass", customer_key, version=1)
```

The same reference works in `processes.start` and in `secrets` when you create a sandbox from an image with a startup command. Anyone who holds an unwrapped reference can use that version, so treat it like the secret itself.

## Use it in a vault

A vault can mix customer-protected entries with ordinary ones. Unwrap the vault to get its customer-protected entries, then pass the result as `vault`. Ordinary entries are delivered as usual.

```typescript Node.js theme={null}
const appEnv = await client.vaults.unwrap("app-env", customerKey);
await sandbox.exec("node app.js", { vault: appEnv });
```

```python Python theme={null}
app_env = client.vaults.unwrap("app-env", customer_key)
sandbox.exec("node app.js", vault=app_env)
```

The unwrapped vault holds the versions its entries pointed at when you unwrapped it. If an entry changes after that, for example because the secret gets a new version, the request fails with `SECRET_VAULT_CHANGED`. Unwrap the vault again and retry.

## Use it as a 1Password token

An `op_token` secret can be customer-protected too. Unwrap it and pass the result as the 1Password `token`. This works for sandbox processes and for [browser fills](https://hyperbrowser.ai/docs/sessions/credentials.md#fill-from-1password):

```typescript Node.js theme={null}
await client.secrets.create({ name: "op-token", type: "op_token", value: process.env.OP_SERVICE_ACCOUNT_TOKEN!, customerKey });
const token = await client.secrets.unwrap("op-token", customerKey);

await sandbox.exec("node app.js", {
  onePassword: { token, vault: "Engineering", fields: { DB_PASS: { item: "Postgres", field: "password" } } },
});
```

```python Python theme={null}
client.secrets.create({"name": "op-token", "type": "op_token", "value": os.environ["OP_SERVICE_ACCOUNT_TOKEN"], "customer_key": customer_key})
token = client.secrets.unwrap("op-token", customer_key)

sandbox.exec(
    "node app.js",
    one_password={"token": token, "vault": "Engineering", "fields": {"DB_PASS": {"item": "Postgres", "field": "password"}}},
)
```

For a browser fill, attach the token by name with `credentials: [{ onePassword: "op-token" }]` when you create the session. Then pass the unwrapped token in the fill's `onePassword.token`.

## Browser sessions

Customer-protected secrets can't be typed into pages. Attaching one to a session fails with `SECRET_REQUIRES_CUSTOMER_UNWRAP`. You can still attach a vault that has customer-protected entries, and fill its other entries. A fill of a customer-protected entry fails with the same code, and nothing is typed.

## Rotate your key

`rewrap` moves a secret's versions to a new key. Each version is unwrapped with the old key and wrapped with the new one on your machine, so the values and version numbers don't change. Versions already wrapped with the new key are skipped, so you can run it again if it's interrupted.

```typescript Node.js theme={null}
const newKey = createCustomerKey(fs.readFileSync("customer-key-2.pem", "utf8"));
await client.secrets.rewrap("db-pass", { from: customerKey, to: newKey });
```

```python Python theme={null}
new_key = create_customer_key(open("customer-key-2.pem").read())
client.secrets.rewrap("db-pass", from_key=customer_key, to_key=new_key)
```

`unwrap` also takes a list of keys and uses the one that wrapped each version, which helps while a rotation is in progress. Vault entries follow their secrets, so a vault needs no change.

## Keep the key in a KMS

To keep the private key in a KMS or HSM, pass your own object instead of `createCustomerKey(...)`. It needs `kid`, `wrap(innerEnvelope, encryptionContext)` and `unwrap(wrappedEnvelope)`. `wrap` returns a compact JWE (`RSA-OAEP-256`, `ECDH-ES` or `ECDH-ES+A256KW`, with `A256GCM`) whose protected header holds `alg`, `enc`, `kid` (the object's `kid`) and `ctx` (the encryption context it was given). ECDH-ES also adds `epk`, and optionally `apu` and `apv`. `unwrap` returns the inner envelope. Either method may return a promise in Node.js, or be a coroutine with `AsyncHyperbrowser` in Python.

## Use the API directly

The SDKs handle the following steps for you.

1. Create the secret with `"protection": "customer"`.
2. Encrypt the value to the platform key, as for any [secret version](https://hyperbrowser.ai/docs/api-reference/add-a-secret-version.md). This is the inner envelope.
3. Wrap the inner envelope with your key, as described under [Keep the key in a KMS](#keep-the-key-in-a-kms), using the secret's `encryptionContext` as `ctx`.
4. Upload a version with `envelope` set to the wrapped envelope. Also send `innerDigest`, the unpadded base64url SHA-256 of the inner envelope, and `innerKid`, the platform key's `kid`.

To use a version, fetch it with [`GET /api/secrets/{id}/versions/{version}/wrapped`](https://hyperbrowser.ai/docs/api-reference/get-a-wrapped-secret-version) and unwrap `envelope`. Then pass the result as `unwrapped`, with the version pinned:

```bash cURL theme={null}
curl -X POST https://api.hyperbrowser.ai/api/sandbox/SANDBOX_ID/processes \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "node migrate.js", "secrets": {"DB_PASS": {"name": "db-pass", "version": 2, "unwrapped": "INNER_ENVELOPE"}}}'
```

For a vault, [`GET /api/vaults/{id}/wrapped`](https://hyperbrowser.ai/docs/api-reference/get-a-wrapped-vault) returns its customer-protected entries. Pass `"vault": {"name": "app-env", "unwrapped": {"DB_PASS": {"version": 2, "unwrapped": "INNER_ENVELOPE"}}}`. To rotate your key, replace a version's wrapping with [`PUT /api/secrets/{id}/versions/{version}/wrapping`](https://hyperbrowser.ai/docs/api-reference/replace-a-secret-version-wrapping).

## Errors

| Code | Status | Meaning |
| - | - | - |
| `SECRET_REQUIRES_CUSTOMER_UNWRAP` | 400 | A customer-protected secret was passed by name, or with `"latest"` instead of a version number, or used where it can't be, such as a browser fill. Pass what `unwrap` returns. |
| `SECRET_VAULT_CHANGED` | 409 | A vault entry changed since you unwrapped the vault. Unwrap it again. |
| `SECRET_DIGEST_MISMATCH` | 409 | The unwrapped envelope isn't the one stored for that version. Check that you passed the right version number. |
| `SECRET_PROTECTION_MISMATCH` | 400 | An unwrapped envelope was passed for an ordinary secret, or a version was uploaded in the other form. |
| `SECRET_VERSION_DUPLICATE` | 409 | Another version already holds this value. Rewrap that version instead of uploading it again. |
| `SECRET_KEY_RETIRED` | 409 | The version was encrypted to a platform key that has been retired. Add a new version. |
| `customer_key_mismatch` | — | Raised by the SDK: none of the keys you passed wrapped this version. |


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