Update ciphertext and metadata

patch

/api/pvlt/1.0/data/collections/{collection}/encrypt/objects

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 and CapCryptoEncrypter capabilities.
• At least one allowing policy and no denying policies for the decrypt and encrypt 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.

  Match pattern: ^[a-zA-Z][a-zA-Z0-9_]*$Max length: 40Example: "customers"

Query parameters

• options - array of strings

  Options for the request.

  • archived - whether to update only archived encrypted objects. If not specified, update only active encrypted objects.

  Each string:

  Allowed values: archived
• expiration_secs - string

  Encrypted object expiration time in seconds. If not set, the default expiration time is used. See the PVAULT_EXPIRATION_TOKENS variable.

  Match pattern: ^[0-9]*$
• adhoc_reason - string

  An ad-hoc reason for accessing the Vault data. Required when reason is set to Other.

• 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.

  Allowed values: AppFunctionality, Analytics, Notifications, Marketing, ThirdPartyMarketing, FraudPreventionSecurityAndCompliance, AccountManagement, Maintenance, DataSubjectRequest, Other
• reload_cache - boolean

  Reloads 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

array of objects required*

Each object:

Additional properties: falseProperties:

• type - string

  The 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 to randomized if not set.

  Default: randomizedAllowed values: randomized, deterministic
• encrypted_object - object required*

  An encrypted object.

  Additional properties: falseProperties:

  • ciphertext - string required*

    The encrypted object base64 cipher text.

  • scope - string

    The 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.

  Additional properties: true

  Example

  {
    "date_of_birth": "1993-02-22",
    "email": "patfar@example.com",
    "first_name": "Pat",
    "last_name": "Far",
    "phone_number": "+11011010101"
  }
• props - array of strings

  The properties to include in the updated encrypted object.

  Each string:

  The name of a property.

  Match pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$Max length: 40Example: "first_name"
• scope - string

  A 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.

  Default: default

Example

[
  {
    "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

The request is successful.

application/json

array of objects required*

Each object:

Properties:

• 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.

Example

[
  {
    "ciphertext": "string"
  }
]

400

The request is invalid.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1001",
  "message": "The access reason is missing.",
  "context": {
    "reason": null
  }
}

401

Authentication credentials are incorrect or missing.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1005",
  "message": "The request is unauthorized.",
  "context": {}
}

403

The caller doesn't have the required access rights.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1007",
  "message": "The operation is forbidden due to missing capabilities.",
  "context": {
    "username": "WebServer"
  }
}

404

The collection or properties aren't found, or property values are invalid.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "objectid": "credit_card",
  "error_code": "PV3003",
  "message": "One or more values are invalid."
}

405

The operation is not allowed.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1026",
  "message": "The operation is not allowed in in-memory mode.",
  "context": {}
}

409

A conflict occurs.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV3218",
  "message": "Concurrent conflicting updates to the same object.",
  "context": {}
}

410

Access to a resource that is no longer available occurs.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1033",
  "message": "The resource is gone.",
  "context": {}
}

500

An error occurs on the server.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1000",
  "message": "Something went wrong",
  "context": {}
}

503

The service is unavailable.

application/json

object required*

Additional properties: falseProperties:

• context - object required*

  The error context.

  Values of additional properties are strings

  Example

  {
    "objectid": "b56dd6aa-35f0-11ed-a261-0242ac120002"
  }
• error_code - string required*

  The error code.

  Example: "PVxxxx"
• message - string required*

  The error message.

  Example: "The object is not found."

Example

{
  "error_code": "PV1009",
  "message": "The operation timed out on the server.",
  "context": {}
}

Try the API

Authorization

API key:

Path parameters

Collection*:

Query parameters

Options:

Expiration_secs:

Adhoc_reason:

Reason*:

Reload_cache:

Request body

Content-Type:

Navigate to the docs of your local Vault installation to try the API directly from there.

Code examples

Example