Skip to main content

http_call request body

Learn about the http_call request body you use to define HTTP requests​

For Vault to send an HTTP request on your behalf using the Invoke HTTP call action operation, you define a JSON object that describes the HTTP request.

Request body format​

The http_call action request body takes the following format JSON:

{
  "template_variables": {
    "<variable name>": "<Vault global identifier>",
  },
  "request": {
    "url": "<request URL template>",
    "method": "<request method>",
    "headers": {
      "<headed name>": "<header content template>"
    },
    "body": "<body template>"
  },
  "include_response_body": <true|false>
}

To specify data driven HTTP requests, the request.url, request.headers, and request.body values can be specified as a template. The template syntax is based on the Go template syntax.

Template syntax​

Strings​

Strings in a specification must escape double quotes (") and backslashes (\). For example, {\"to\": \"{{ .to_email }}\", \"message\": \"Hello {{ .first_name }}!\" }

Variables​

The source of variable values is defined in the "template_variables" object.

Variables in the template are referenced using the {{ .variable_name }} syntax. If the variable value refers to an object, you access its properties using the {{ .variable_name.property_name }} syntax. For example, if the variable customer is sourced from 'pvlt:read_object:customers::bb5e17ce-38b1-4b3f-9b4b-40801f9672d1:, 'customer.first_name refers to the first name property of the customers collection object with the ID bb5e17ce-38b1-4b3f-9b4b-40801f9672d1.

To prevent injection attacks, Vault automatically escapes double quotes (") and backslashes (\) in string variables passed to the template. Computed values are not escaped by default, so escape them manually with the escape_quotes function. If the template is used to generate a request body in a format other than JSON, escaping must be done manually.

Functions​

You use functions in the template with the pipe (|) syntax as in {{ .variable_name | function_name }}. For example, to convert a string to upper case, you use {{ .variable_name | upper }}.

In addition to the standard Go template functions, Vault provides functions to perform common operations.

FunctionDescription
upperConvert a string to upper case.
lowerConvert a string to lower case.
titleConvert a string to title case.
escape_quotesEscape double quotes (") and backslashes (\) in a string to be embedded as a JSON string literal.
unescape_quotesUnescape the default vault escaping of double quotes (") and backslashes (\) in a string.
to_jsonConvert a value to a JSON string.
from_jsonParse a JSON string into a value.

"template_variables"​

This object contains a key-value map of template variable name to Vault global identifier.

Vault global identifier​

A Vault global identifier contains information about how to access data and where it's stored in Vault. The format of a Vault global identifier is:

pvlt:[operation]:[collection]:[property[.transformation?]?]:[id]:[options]

Where:

  • operation is the operation to retrieve the object or object property, being one of:
    • read_object - Read an object from a collection.
    • detokenize - Detokenize a token from a collection.
    • decrypt_object - Decrypt an encrypted object.
  • collection is the collection where the object is stored or used to encrypt the object.
  • property is a property of the object to retrieve. If not provided, all properties of the object are retrieved.
    • If the property includes a transformation, the transformation is applied to the property value before returning it.
  • id is the reference or details of the item to use in the operation.
    • For read_object operations, the ID of an object.
    • For detoeknize operations, the ID of a token.
    • For decrypt_object operations, the encrypted object ciphertext.
  • options - Reserved for future use to hold options to control the behavior of the operation.

Here are some Vault global identifier examples:

  • Read an object from a collection: 
    pvlt:read_object:customers::bb5e17ce-38b1-4b3f-9b4b-40801f9672d1:
  • Read a property from an object in a collection: 
    pvlt:read_object:customers:email:bb5e17ce-38b1-4b3f-9b4b-40801f9672d1:
  • Detokenize a property with a transformation from a collection: 
    pvlt:detoeknize:credit_cards:number.mask:bb5e17ce-38b1-4b3f-9b4b-40801f9672d1:
  • Decrypt an encrypted object: 
    pvlt:decrypt_object:customers::AQABnYFzkW3gMiS3+pAH2ZeU7TgR3jCc43kdHii+sIzGog7/+F8BYnn8KvEwiunkgtP1Z86jtRpA29BaQeD4MT8wmN9gA0OC:

On this page