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: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.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.
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 asvault. Ordinary entries are delivered as usual.
SECRET_VAULT_CHANGED. Unwrap the vault again and retry.
Use it as a 1Password token
Anop_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:
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 withSECRET_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 ofcreateCustomerKey(...). 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.- Create the secret with
"protection": "customer". - Encrypt the value to the platform key, as for any secret version. This is the inner envelope.
- Wrap the inner envelope with your key, as described under Keep the key in a KMS, using the secret’s
encryptionContextasctx. - Upload a version with
envelopeset to the wrapped envelope. Also sendinnerDigest, the unpadded base64url SHA-256 of the inner envelope, andinnerKid, the platform key’skid.
GET /api/secrets/{id}/versions/{version}/wrapped and unwrap envelope. Then pass the result as unwrapped, with the version pinned:
cURL
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.