Add a secret version

Changed on

Uploads a new value as the secret's next version. Encrypt the value on your side as a compact JWE (RSA-OAEP-256 and A256GCM) to the key from GET /api/secrets/public-key, with the protected header {alg, enc, kid, ctx}, where ctx is the secret's encryptionContext. The SDKs and CLI do this for you. A secret keeps at most 10 versions. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need the secrets.manage scope. When you're signed in rather than using an API key, you must be a team owner or admin (otherwise 403 SECRETS_ADMIN_REQUIRED).

post/api/secrets/{id}/versions

Request

Path parameters

idstring uuid required

Secret ID.

Request body

envelopestring required

The value, encrypted on your side as a compact JWE: five canonical, unpadded base64url segments. Wrap the content key with RSA-OAEP-256 using the key from GET /api/secrets/public-key, and encrypt the content with A256GCM. The protected header must hold exactly alg (RSA-OAEP-256), enc (A256GCM), kid (the public key's kid) and ctx (the secret's encryptionContext, copied verbatim). The plaintext is the value as UTF-8: any string for secret; a base32 seed (spaces, hyphens and line breaks are ignored, = padding only at the end) or an otpauth://totp/ URI (with secret and optionally algorithm SHA1, SHA256 or SHA512, digits 6 or 8, and period 1-300) for totp; a 1Password service account token for op_token. The value can be at most 32 KiB, without NUL bytes, and the envelope at most 64 KiB. The API checks the envelope's structure but can't decrypt it, so it can't check the value: an invalid TOTP seed returns 422 SECRET_VALUE_INVALID when it's used. The Hyperbrowser SDKs and CLI validate the value and build the envelope for you, so we recommend using them rather than encrypting by hand. For a customer-protected secret, envelope is that inner envelope wrapped with your own key as another compact JWE: RSA-OAEP-256, ECDH-ES or ECDH-ES+A256KW key management with A256GCM, and a protected header holding exactly alg, enc, kid (your key's ID, 1-256 printable ASCII characters) and ctx (the secret's encryptionContext), plus epk, and optionally apu and apv, with ECDH-ES.

innerDigeststring

Customer-protected secrets only, and required for them: the unpadded base64url SHA-256 of the inner envelope's compact form.

innerKidstring

Customer-protected secrets only, and required for them: the kid of the platform public key the inner envelope was encrypted to. It must be the current key (otherwise 409 SECRET_KEY_OUTDATED).

Response

Success

versioninteger required
kidstring required

ID of the platform public key the envelope (for a customer-protected secret, the inner envelope) was encrypted to.

createdAtstring date-time required
outerKidstring

Customer-protected secrets only: the ID of your key that wrapped this version.

retiresAtstring date-time nullable

When the platform key this version was encrypted to is retired. Uses after then fail with 409 SECRET_KEY_RETIRED; add a new version. Null when no retirement is scheduled.

Changes

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      endpoint added