Method: Rotate Key¶
Description¶
This endpoint rotates the named encryption key in the specified vault. After rotation, new plaintext requests will be encrypted with the new version of the named key. To upgrade ciphertext to be encrypted with the latest version of the key, use the /rewrap endpoint.
Note
This endpoint requires at least Write permission in the affected vault.
URL Syntax¶
/api/{version}/transparent/:vaultid/keys/:name/rotate
HTTP Method¶
POST
Successful HTTP Response¶
201
Parameters¶
Parameter name | Description | Parameter type | Type | Default | Mandatory | Comment |
---|---|---|---|---|---|---|
X-Http-Token | StoredSafe token | HTTP Header | String | 1) | Preferred method | |
token | StoredSafe token | JSON-encoded | String | 1) | Legacy method | |
vaultid | Vault-ID | URL-encoded | String | Yes | ||
name | Key name | URL-encoded | String | Yes |
Note
1) One of the methods is required.
Response Attributes¶
Attribute | Description | Type |
---|---|---|
CALLINFO.errorcodes | Number of errors | Integer |
CALLINFO.errors | Number of errors | Integer |
CALLINFO.general | Information | Array |
CALLINFO.handler | Handler used | String |
CALLINFO.status | SUCCESS or FAIL | String |
CALLINFO.token | Rotated StoredSafe token 1) | String |
CALLINFO.key_version | Latest key version | String |
CALLINFO.objectid | Object-ID | String |
DATA | Supplied data in prior API-call | String |
HEADERS.(headers) | HTTP Headers | String |
PARAMS | Route parameters (empty) | Array |
ERRORCODES | Error code and text 2) | Object |
ERRORS | Error code and text 2) | Array |
Note
1) Token to be used in subsequent calls
2) Only present if errors
Examples¶
Rotate the key my-new-key
in the vault (vaultid) 179, creating a new
random encryption key, with a new version number.
Request
POST /api/1.0/transparent/179/keys/my-new-key/rotate
x-http-token: your_storedsafe_token
Response
HTTP/2 200
Content-type: application/json; charset=UTF-8
{
"CALLINFO": {
"errorcodes": 0,
"errors": 0,
"general": [],
"handler": "EncryptionHandler",
"status": "SUCCESS",
"token": "rotated_storedsafe_token",
"name": "my-new-key",
"key_version": "2",
"objectid": "8743"
},
"DATA": {
"name": "my-new-key",
"vaultid": "179",
"token": "your_storedsafe_token",
},
"HEADERS": {
"Accept": "*/*",
"Content-Length": "169",
"Content-Type": "application/json",
"Host": "safe.domain.cc",
"User-Agent": "curl/7.64.1",
"X-Http-Token": "your_storedsafe_token"
},
"PARAMS": []
}