Encrypt

post

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

Creates ciphertext that includes the values of an object's properties. Supports bulk operations.

You can encrypt:

Objects stored in Vault by providing their ID.
Fields not stored in Vault by providing a map of their properties and property values. However, fields must conform to the collection schema specified in the request.
Ciphertext. This enables you to create a ciphertext including a subset of another ciphertext's properties or with a different encryption type or scope. To update the property values, use the update encrypted operation.

💡 For brevity, this guide uses the term object to refer to the content being encrypted.

If any request details are invalid, none of the objects are encrypted.

You can generate ciphertext for the encrypted object with a random initialization vector (randomized) or based on the collection name, input object, and scope (deterministic).

Using props, you can request that the ciphertext include a subset of the collection schema's properties. However, if a property isn't present in the object or the property value is null, it is not included in the encrypted ciphertext. Also, if you want to include built-in properties, you must include them in props.

The role performing this operation must have both of these:

The CapCryptoEncrypter capability.
At least one allowing policy and no denying policies for the encrypt operation 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

Header parameters

X-Tenant-Id - array of strings
List of tenant IDs to enforce on the 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

expiration_secs - string
Encrypted object expiration time in seconds. If not set, the default expiration time is used. See the PVAULT_EXPIRATION_TOKENS variable. If set to an empty value, the encrypted will be marked to not expire.
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
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
custom_audit - string
Custom audit information to be included in the audit log.
reload_cache - boolean
Reloads the cache before the action.

Request body

Details of the encryption request.

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
object - object required*
The input object, defined as one and only one of the following properties.
- id: the ID of an object.
- fields: property values of an object.
- encrypted: an encrypted object.
- request_index: the index of the object in the request array.
In stateless mode, id is not supported and either fields or encrypted must be supplied.
Min properties: 1Max properties: 1Additional properties: falseProperties:
- id - string
  The ID of an object.
  Format: uuid
- fields - object
  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" }
- encrypted - object
  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.
- request_index - integer
  The index of the object in the request array.
  Greater than or equal to: 0
Example
{ "fields": { "first_name": "John", "email": "patfar@example.com" } }
props - array of strings
A list of the properties to include in the encrypted object. If not provided, all properties are included, including the built-in properties, but omitting the object ID.
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 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
tags - array of strings
Tags to attach to the metadata of the encrypted object. The maximum number of allowed tags is defined by the PVAULT_DB_MAX_TOKEN_TAGS environment variable (default 10). Tags are not supported for the deterministic encryption type.
Less than or equal to: 10Each string:
Max length: 256Example: "credit_cards"

Example
[
  {
    "object": {
      "fields": {
        "email": "john@work.com",
        "phone_number": "555-555-5555"
      }
    },
    "props": [
      "phone_number",
      "email"
    ]
  }
]

Possible responses

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"
  }
]

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

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."
error_url - string
The URL to the error documentation.
Example: "https://docs.piiano.com/api/error-codes#PV1005"

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

Try the API

Authorization

API key:

Path parameters

Collection*:

Query parameters

Expiration_secs:

Adhoc_reason:

Reason:

Custom_audit:

Reload_cache:

Headers

X-Tenant-Id:

Request body

Content-Type:

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

Code examples

Example

Request​

Header parameters​

Path parameters​

Query parameters​

Request body​

Possible responses​

Try the API

Authorization

Path parameters

Query parameters

Headers

Request body

Code examples

Request

Header parameters

Path parameters

Query parameters

Request body

Possible responses