Decrypt

post

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

Decrypts ciphertext. Supports bulk operations.

To decrypt ciphertext, the request must include the scope used when the ciphertext was encrypted. By default, only ciphertext considered active is decrypted. Ciphertext is considered active when its metadata expiration property is for the current or a future date. If options is set to archived, the ciphertext is only decrypted if its metadata expiration property is for a date in the past.

By default, all property values from the ciphertext are returned. Use props to return a subset of the encrypted property values.

If any request details are invalid, none of the ciphertexts are decrypted.

The role performing this operation must have both of these:

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

options - array of strings
Options for the operation. Options include:
- archived – whether to decrypt only archived objects. If not specified, decrypts only active objects.
- include_metadata - show the encrypted object metadata.
Each string:
Option for the operation.
Allowed values: archived, include_metadata
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
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 decryption request.

application/json

array of objects required*

Each object:

Additional properties: falseProperties:

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.
props - array of strings
The list of property names and transformers to include in the decrypted object. If not set, return all encrypted property values.
Each string:
Example: "credit_card_no"

Example
[
  {
    "encrypted_object": "...",
    "props": [
      "phone_number",
      "email"
    ]
  }
]

Possible responses

The request is successful.

application/json

array of objects required*

Each object:

Additional properties: falseProperties:

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

metadata - object
Additional properties: falseProperties:
- type - string required*
  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
- scope - string required*
  The scope of the tokens.
  Example: "default"
- expiration - string
  Effective expiry time of the encrypted object (UTC).
  Format: date-timeNullable: true
- tags - array of strings required*
  Tags associated with the encrypted object.
  Each string:
  Max length: 256Example: "credit_cards"

Example
[
  {
    "fields": {
      "date_of_birth": "1993-02-22",
      "email": "patfar@example.com",
      "first_name": "Pat",
      "last_name": "Far",
      "phone_number": "+11011010101"
    },
    "metadata": {
      "type": "randomized",
      "scope": "default",
      "expiration": "2019-08-24T14:15:22Z",
      "tags": [
        "credit_cards"
      ]
    }
  }
]

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.

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

Options:

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