Promote KMS server

Content Platform for Cloud Scale Management API Reference

Part Number

You can promote a configured secondary external KMS server to the primary server. Any primary server is demoted to a secondary server.

Any external KMS server designated as a secondary server can be promoted to a primary server. Promoting a secondary server demotes the existing primary server to secondary status.

Normally, key encryption keys (KEKs) are synchronized between the primary server and any secondary servers. If a secondary server is promoted but has an incomplete set of KEKs, HCP for cloud scale tries to populate missing KEKs using cached KEKs. If the promoted server cannot produce a KEK and the KEK is not cached, then all data associated with the missing KEK remains unavailable until the previous primary server is repaired and populates the newly promoted primary server with the missing KEK.

HTTP request syntax (URI)

POST https://host_ip:9099/mapi/v1/kmip/promote_server

Request structure

"name": "name"
Parameter Required Type Description
name Yes String The user-assigned name of the KMS server you want to promote. Type up to 63 Unicode characters.

Response structure

The response body structure is:

  "name": "label",
  "host": "host_name",
  "port": nnnnn,
  "isPrimary": {true|false},
  "isTLS12Enabled": {true|false},
  "httpsCiphers": "cipher_1[,...,cipher_n]",
  "isOnline": {true|false},
  "uuid": "uuid"




name String The name of the KMS server.
host String The host name or IP address of the KMS server.
port Integer The port number of the KMS server.
isPrimary Boolean true.
isTLS12Enabled Boolean true if TLS v1.2 is enabled, false otherwise.
httpsCiphers String A string of comma-separated cyphers.
isOnline Boolean true if server is online, false if server is offline.
uuid UUID The UUID of the server.

Return codes

Status code

HTTP name


200 OK The request was executed successfully.
401 Unauthorized Access was denied because credentials are not valid.
405 Method Not Allowed The specified HTTP method is not allowed. Resend using POST.
503 Service Unavailable External KMS servers have not been set up. Configure connection to an external KMS server and resend.


Request example:

POST "MyServer"

JSON request:

"name": "myServer"

JSON response:

  "name": "myServer",
  "host": "myHost_0",
  "port": 9876,
  "isPrimary": true,
  "isTLS12Enabled": false,
  "isOnline": true,
  "uuid": "uuid"