Update ciphertext and metadata
Returns ciphertext that includes property values from another ciphertext. Supports bulk operations.
This enables the creation of encrypted ciphertext without exposing encrypted property values to the user.
The returned ciphertext can have different encryption type, scope, properties, or property values to the source ciphertext. Any property values in the source ciphertext not updated in the request are preserved in the new ciphertext as long as they are included in props
.
For example, if the source ciphertext contains first_name
, last_name
, and telephone_number
and props
specifies [first_name, last_name]
, then telephone_number
isn't included in the new encrypted ciphertext.
The request must include the scope used to encrypt the source ciphertext.
If any request details are invalid, no ciphertexts are created.
The role performing this operation must have both of these:
- The
CapCryptoDecrypter
andCapCryptoEncrypter
capabilities. - At least one allowing policy and no denying policies for the
decrypt
andencrypt
operations for each of the collection properties specified in the call.
See identity and access management for more information about how Vault uses capabilities to control access to operations and policies to control access to data.
Request
Path parameters
collection
- string required*The name of a collection.
Query parameters
options
- array of stringsOptions for the request.
archived
- whether to update only archived encrypted objects. If not specified, update only active encrypted objects.
expiration_secs
- stringEncrypted object expiration time in seconds. If not set, the default expiration time is used. See the
PVAULT_EXPIRATION_TOKENS
variable.adhoc_reason
- stringAn ad-hoc reason for accessing the Vault data. Required when
reason
is set toOther
.reason
- string required*Details of the reason for requesting the property. The default is set when no access reason is provided and PVAULT_SERVICE_FORCE_ACCESS_REASON is false.
reload_cache
- booleanReloads the cache before the action.
Request body
Details of the update encrypted object request. The request includes the encrypted object to update and the property values to update the encrypted object with.
- application/json
type
- stringThe type of the encryption:
randomized
- generates a different randomized unpredictable, non-repeating ciphertext each time.deterministic
- generates the ciphertext deterministically based on the collection name, input object, and scope. Defaults torandomized
if not set.
encrypted_object
- object required*An encrypted object.
ciphertext
- string required*The encrypted object base64 cipher text.
scope
- stringThe scope used to encrypt the object. By default, it uses the scope of the encrypted object.
fields
- object required*A list of maps of object properties and their values.
Example{
"date_of_birth": "1993-02-22",
"email": "patfar@example.com",
"first_name": "Pat",
"last_name": "Far",
"phone_number": "+11011010101"
}props
- array of stringsThe properties to include in the updated encrypted object.
Each string:The name of a property.
scope
- stringA classification for the updated encrypted object that is added to the ciphertext as associated data (AAD). An object encrypted with a scope can be decrypted only with the same scope.
[
{
"type": "randomized",
"encrypted_object": {
"ciphertext": "string",
"scope": "string"
},
"fields": {
"date_of_birth": "1993-02-22",
"email": "patfar@example.com",
"first_name": "Pat",
"last_name": "Far",
"phone_number": "+11011010101"
},
"props": [
"first_name"
],
"scope": "default"
}
]
Possible responses
- 200
- 400
- 401
- 403
- 404
- 405
- 409
- 410
- 500
- 503
The request is successful.
- application/json
ciphertext
- string required*The encrypted object is a base64 ciphertext of the request fields and built-in fields such as timestamps and expiration time. It does not include the ID field.
[
{
"ciphertext": "string"
}
]
The request is invalid.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1001",
"message": "The access reason is missing.",
"context": {
"reason": null
}
}
Authentication credentials are incorrect or missing.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1005",
"message": "The request is unauthorized.",
"context": {}
}
The caller doesn't have the required access rights.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1007",
"message": "The operation is forbidden due to missing capabilities.",
"context": {
"username": "WebServer"
}
}
The collection or properties aren't found, or property values are invalid.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"objectid": "credit_card",
"error_code": "PV3003",
"message": "One or more values are invalid."
}
The operation is not allowed.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1026",
"message": "The operation is not allowed in in-memory mode.",
"context": {}
}
A conflict occurs.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV3218",
"message": "Concurrent conflicting updates to the same object.",
"context": {}
}
Access to a resource that is no longer available occurs.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1033",
"message": "The resource is gone.",
"context": {}
}
An error occurs on the server.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1000",
"message": "Something went wrong",
"context": {}
}
The service is unavailable.
- application/json
context
- object required*The error context.
Values of additional properties are stringsExample{
"objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
}error_code
- string required*The error code.
message
- string required*The error message.
error_url
- stringThe URL to the error documentation.
{
"error_code": "PV1009",
"message": "The operation timed out on the server.",
"context": {}
}
Path parameters
Query parameters
Request body
Code examples