Skip to main content
A customer-protected secret is a secret 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 and use them as 1Password tokens. They can’t be typed into browser pages.
Customer-protected secrets need Node SDK 1.5.0 or Python SDK 1.15.0. They’re part of Secrets 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 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:
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.
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.
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.
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:
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.
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. This is the inner envelope.
  3. Wrap the inner envelope with your key, as described under 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 and unwrap envelope. Then pass the result as unwrapped, with the version pinned:
cURL
For a vault, GET /api/vaults/{id}/wrapped 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.

Errors