> ## 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.

# Replace a secret version's wrapping

> Rewrap a customer-protected version with another of your keys.

See [customer-protected secrets](https://hyperbrowser.ai/docs/sandboxes/customer-keys.md#rotate-your-key) for SDK examples. The SDKs' `secrets.rewrap()` does this for every version.


## OpenAPI

````yaml openapi.json PUT /api/secrets/{id}/versions/{version}/wrapping
openapi: 3.0.1
info:
  title: Hyperbrowser API
  version: 1.0.0
servers:
  - url: https://api.hyperbrowser.ai
    description: Production server
security: []
paths:
  /api/secrets/{id}/versions/{version}/wrapping:
    put:
      summary: Replace a secret version's wrapping
      description: >-
        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).
      operationId: replaceSecretVersionWrapping
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Secret ID.
        - name: version
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Version number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceSecretVersionWrappingParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrappedSecretVersion'
        '400':
          description: >-
            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).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '403':
          description: >-
            API_KEY_SCOPE_DENIED (the API key lacks a required scope),
            SECRETS_FEATURE_DISABLED, or SECRETS_ADMIN_REQUIRED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '404':
          description: SECRET_NOT_FOUND or SECRET_VERSION_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '409':
          description: 'SECRET_DIGEST_MISMATCH: `innerDigest` isn''t this version''s.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ReplaceSecretVersionWrappingParams:
      type: object
      properties:
        envelope:
          type: string
          maxLength: 65536
          description: >-
            The version's inner envelope, wrapped with your new key, in the same
            form as a customer-protected version upload.
        innerDigest:
          type: string
          description: >-
            The version's `innerDigest`. It must match: only the wrapping
            changes, never the value (otherwise 409 SECRET_DIGEST_MISMATCH).
      required:
        - envelope
        - innerDigest
      additionalProperties: false
    WrappedSecretVersion:
      type: object
      description: >-
        A customer-protected version as stored. Unwrap `envelope` with your key
        to get the inner envelope each use passes as `unwrapped`.
      properties:
        version:
          type: integer
          minimum: 1
        kid:
          type: string
          description: ID of the platform public key the inner envelope is encrypted to.
        retiresAt:
          type: string
          format: date-time
          nullable: true
          description: When that platform key is retired, or null.
        outerKid:
          type: string
          description: ID of your key that wrapped the version.
        innerDigest:
          type: string
          description: >-
            Unpadded base64url SHA-256 of the inner envelope. Check the envelope
            you unwrap against it.
        envelope:
          type: string
          description: The wrapped envelope, which only your key can open.
      required:
        - version
        - kid
        - retiresAt
        - outerKid
        - innerDigest
        - envelope
    SecretErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code, such as SECRET_NOT_FOUND.
        message:
          type: string
        error:
          type: string
          description: >-
            Set instead of `code` by authentication and API key scope errors
            (API_KEY_SCOPE_DENIED).
        requiredScopes:
          type: array
          items:
            type: string
          description: The scope the API key is missing, with API_KEY_SCOPE_DENIED.
        retryable:
          type: boolean
          description: >-
            Whether repeating the same request can succeed. Set on delivery
            errors.
        details:
          type: object
          additionalProperties: true
          description: >-
            Extra information for some codes, such as `origin` for
            CREDENTIAL_ORIGIN_NOT_ALLOWED or `pages` for
            CREDENTIAL_PAGE_AMBIGUOUS.
      description: >-
        HTTP failure. Secret errors include `code` and `message`; request
        validation errors include only `message`; API key scope errors include
        `error`, `message` and `requiredScopes`.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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