---
title: "Replace a secret version's wrapping"
method: PUT
path: "/api/secrets/{id}/versions/{version}/wrapping"
---

# Replace a secret version's wrapping

`PUT /api/secrets/{id}/versions/{version}/wrapping`

## Request

- Base URL: `https://api.hyperbrowser.ai`
- URL: `https://api.hyperbrowser.ai/api/secrets/{id}/versions/{version}/wrapping`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/docs/api/secrets/:id/versions/:version/wrapping/put.ts> (a function with typed inputs; its response is checked against the schema)

Replaces a customer-protected version's wrapped envelope with one wrapped with another of your keys, to rotate your key. The value and version number don't change. The SDKs' `rewrap` does this for every version. See [Customer-protected secrets](/sandboxes/customer-keys). 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).

## Path parameters

- `id` string, uuid, required
- `version` integer, required

## Request body

- ReplaceSecretVersionWrappingParams
  - `envelope` string, required: The version's inner envelope, wrapped with your new key, in the same form as a customer-protected version upload.
  - `innerDigest` string, required: The version's `innerDigest`. It must match: only the wrapping changes, never the value (otherwise 409 SECRET_DIGEST_MISMATCH).

## Response `200`

Success

- WrappedSecretVersion: A customer-protected version as stored. Unwrap `envelope` with your key to get the inner envelope each use passes as `unwrapped`.
  - `version` integer, required
  - `kid` string, required: ID of the platform public key the inner envelope is encrypted to.
  - `retiresAt` string, date-time, nullable, required: When that platform key is retired, or null.
  - `outerKid` string, required: ID of your key that wrapped the version.
  - `innerDigest` string, required: Unpadded base64url SHA-256 of the inner envelope. Check the envelope you unwrap against it.
  - `envelope` string, required: The wrapped envelope, which only your key can open.

## Other responses

- `400`: Invalid request body, SECRET_ENVELOPE_INVALID (the wrapped envelope isn't valid for this secret), or SECRET_PROTECTION_MISMATCH (the secret isn't customer-protected).
- `401`: Authentication required.
- `403`: API_KEY_SCOPE_DENIED (the API key lacks a required scope), SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
- `404`: SECRET_NOT_FOUND or SECRET_VERSION_NOT_FOUND.
- `409`: SECRET_DIGEST_MISMATCH: `innerDigest` isn't this version's.
- `500`: Internal server error.

## Changes

- **2026-11-10** `94dc06948680`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/api/secrets/:id/versions/:version/wrapping/put.md)

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)