Enables or disables the retain recovery key setting for the customer, optionally removing old recovery keys.
post /bitlocker/api/retainRecoveryKey
https://{server-hostname}:8383/bitlocker/api/retainRecoveryKey
DataEncryption.CREATECopied!
Authorization: d92d4xxxxxxxxxxxxx15f52
Set to true to enable recovery key retention, false to disable. Required.
Optional. Set to true to immediately remove old recovery keys. Only relevant when disabling retention (retainRecoveryKeyEnabled=false).
curl --request POST \
--url https://appdomain/bitlocker/api/retainRecoveryKey \
--header 'Accept: application/json' \
--header 'Authorization: d92d4xxxxxxxxxxxxx15f52' \
--header 'Content-Type: application/json' \
--data '{"retainRecoveryKeyEnabled":true,"removeOldRecKey":false}'Enable recovery key retention
{
"retainRecoveryKeyEnabled": true,
"removeOldRecKey": false
}
Disable recovery key retention and remove old keys
{
"retainRecoveryKeyEnabled": false,
"removeOldRecKey": true
}
Current state of the recovery key retention setting
Persisted parameter value as string ('true' or 'false')
Validation error code raised when the request body is missing, malformed, exceeds max-len=100, or fails retainRecoveryKeyTemplate validation (retainRecoveryKeyEnabled / removeOldRecKey not boolean)
Detailed message identifying which body key failed validation or why the payload was rejected
Unauthorized error code returned when authentication credentials are missing, expired, or invalid (authentication=required)
Authentication failure reason
Forbidden error code returned when the authenticated user does not have the required uem-roles (e.g., DataEncryption_Admin or DataEncryptionRecoveryKey_Admin)
Message indicating insufficient privileges to access this resource
Rate limit error code returned when the API call threshold (configured via threshold/duration in security XML) is exceeded; client is locked out for lock-period minutes
Rate limit exceeded message with retry guidance
Internal server error code (DCAPIErrorCodes.INTERNAL_ERROR) thrown when persisting the retain-recovery-key parameter or removing old recovery keys fails
Server-side error message — typically 'Exception while forming response'
Successful update of retain recovery key setting
{
"retainRecoveryKeyEnabled": true,
"paramValue": "true"
}
Invalid or malformed request body
{
"errorCode": 40001,
"errorMsg": "Invalid request parameters"
}
Authentication credentials missing or invalid
{
"errorCode": 40101,
"errorMsg": "Authentication failed"
}
User does not have DataEncryptionRecoveryKey_Admin role
{
"errorCode": 40301,
"errorMsg": "Insufficient privileges to access this resource"
}
Throttle limit exceeded; client locked out for lock-period minutes
{
"errorCode": 42901,
"errorMsg": "Too many requests. Please retry after the cooldown period"
}
Internal server error — thrown from catch block via DCAPIException
{
"errorCode": 10000,
"errorMsg": "Exception while forming response"
}
![]()
Duration: 1 minute | Threshold: 30 | Lock period: 5 minutes
Duration - Time window for the threshold.
Threshold - Number of API calls allowed within the specified duration.
Lock Period - Wait time before consecutive API requests.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.
© 2026, Zoho Corporation Pvt. Ltd. All Rights Reserved.