> ## Documentation Index
> Fetch the complete documentation index at: https://support.fortanix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate a security object to an existing security object.

> For two keys R and S, where R is the key to be replaced,
and S is the intended replacement, this operation will
- Rename R to the name provided in the request
- Establish an replaced-replacement between R and S
- Assign R's old name to S
The metadata of S should be mostly same as that of R, and
it is not possible to update any fields of S while
performing this operation. If S does not have any custom
metadata or a rotation policy, any corresponding values
from R will be copied over to S.
For now, this operation is not supported if R, S, or both
are externally-backed keys.

## OpenAPI

````json POST /crypto/v1/keys/replace
{
  "openapi": "3.0.0",
  "info": {
    "title": "Fortanix DSM REST API",
    "description": "This is a set of REST APIs for accessing the Fortanix Data Security Manager. This includes APIs for managing accounts, and for performing cryptographic and key management operations. \n\n **Note:** \n- All binary input should be base64-encoded. These fields are marked with `format: byte`. \n- For forward compatibility, any API client is expected to ignore any fields in the response not explicitly mentioned in the documentation. We reserve the right to add new fields at any time to provide new functionality without affecting existing API clients.",
    "termsOfService": "https://www.fortanix.com/legal/terms/",
    "contact": {
      "name": "Fortanix Support",
      "url": "https://support.fortanix.com/",
      "email": "support@fortanix.com"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "version": "0.1.0-20260526"
  },
  "servers": [
    {
      "url": "https://amer.smartkey.io"
    }
  ],
  "paths": {
    "/crypto/v1/keys/replace": {
      "post": {
        "operationId": "ReplaceSobject",
        "tags": [
          "Keys"
        ],
        "security": [
          {
            "bearerToken": []
          },
          {
            "apiKeyAuth": []
          }
        ],
        "summary": "Rotate a security object to an existing security object.",
        "description": "For two keys R and S, where R is the key to be replaced,\nand S is the intended replacement, this operation will\n- Rename R to the name provided in the request\n- Establish an replaced-replacement between R and S\n- Assign R's old name to S\nThe metadata of S should be mostly same as that of R, and\nit is not possible to update any fields of S while\nperforming this operation. If S does not have any custom\nmetadata or a rotation policy, any corresponding values\nfrom R will be copied over to S.\nFor now, this operation is not supported if R, S, or both\nare externally-backed keys.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SobjectReplaceRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Nothing is returned on success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SobjectReplaceRequest": {
        "allOf": [
          {
            "type": "object",
            "description": "Request to rotate a security object to an existing security object.",
            "properties": {
              "replaced": {
                "$ref": "#/components/schemas/SobjectDescriptorPersisted"
              },
              "replaced_new_name": {
                "type": "string",
                "maxLength": 4096,
                "pattern": "^[^\\n]*[^\\s\\n][^\\n]*$",
                "description": "New name for the replaced security object."
              },
              "replacement": {
                "$ref": "#/components/schemas/SobjectDescriptorPersisted"
              }
            },
            "required": [
              "replaced",
              "replaced_new_name",
              "replacement"
            ]
          }
        ]
      },
      "SobjectDescriptorPersisted": {
        "description": "Uniquely identifies a persisted sobject.",
        "oneOf": [
          {
            "title": "SobjectDescriptorPersistedVariantKid",
            "type": "object",
            "properties": {
              "kid": {
                "type": "string",
                "format": "uuid"
              }
            },
            "required": [
              "kid"
            ]
          },
          {
            "title": "SobjectDescriptorPersistedVariantName",
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 4096,
                "pattern": "^[^\\n]*[^\\s\\n][^\\n]*$"
              }
            },
            "required": [
              "name"
            ]
          }
        ]
      }
    }
  }
}
````