String Interpolation Syntax

The purpose of string interpolating is to be able to extract dynamic data at run-time, from previous stages of an authentication flow into the following stages. This will be needed in cases when it is impossible to hardcode such dynamic data, for example, temporary IDs or tokens. The string interpolation block will be replaced by the actual dynamic data that is generated each time the particular authentication flow runs.

The syntax allows you to create a template (interpolation string) for the value to be extracted from the specified location. While using a template to configure a request, you can only reference requests and responses already executed during the current flow.

The interpolation string uses the double curly braces {{ and }} as the boundaries for each block and consists of two general parts: Source data and Functions, that should be defined in order to do the interpolation.

The source of data configuration consists of the following parts:

Data context: each interpolation string must start with the auth_object prefix which defines the context of the interpolation execution. In the future, you will be able to pull information from other contexts such as secrets vaults, etc.
Stage from which the data is to be collected
Request/response: The request or response of that stage
Location inside the request/response: URL, headers, body

📘
Note:
The authentication process produces HTTP requests and receives HTTP responses. A request-response pair is named stage in terms of the template syntax.

Functions :

Functions are separated by the | character, and support chaining multiple functions with the same character.

Format: {{ <source of data> | function 1 | function 2 }}

The parts comprise the following components:

Part Components

Source of data 1. Data context: auth_object
2. Stage: stageN, where N is the number of the stage (1, 2, 3...)
2. Request/response: request, response
3. Location inside the request/response: url, headers, body

There are three common use cases:

1. The exact stage number is known.
Example: {{ auth_object.stage1.response.headers | <function> }}

2. The exact stage number is unknown or can change (any_stage).
When using the any_stage option the matcher will look across all the stages for a match with your interpolation, and return the latest one (chronologically) from the flow.

Example: {{ auth_object.any_stage.response.headers | <function> }}

3. Alternatively, if the source data needs to be generated outside of the authentication flow, such as OTP token generation, see the OTP chapter.

Function The string interpolation syntax supports the chaining of functions executing from left to right, and each function should start with the pipe character | . The functions are applied in the relevant order. It means that in the example below, first the get will be applied, and then the match.

Functions have two components:
1. Name: get, match, encode
2. Parameters: see functions description below for additional info.

Parameters are separated from the function name by a colon:

Example: {{ auth_object.stage1.response.headers | get: '/Set-Cookie' }}

Example with chained functions: {{ auth_object.stage1.response.headers | get: '/Set-Cookie' | match:/accessToken":"(.\*)"}/}}

Part	Components
Source of data	1. Data context: `auth_object` 2. Stage: `stageN`, where `N` is the number of the stage (1, 2, 3...) 2. Request/response: `request`, `response` 3. Location inside the request/response: `url`, `headers`, `body` There are three common use cases: 1. The exact stage number is known. Example: `{{ auth_object.stage1.response.headers \| <function> }}` 2. The exact stage number is unknown or can change (any_stage). When using the `any_stage` option the matcher will look across all the stages for a match with your interpolation, and return the latest one (chronologically) from the flow. Example: `{{ auth_object.any_stage.response.headers \| <function> }}` 3. Alternatively, if the source data needs to be generated outside of the authentication flow, such as OTP token generation, see the OTP chapter.
Function	The string interpolation syntax supports the chaining of functions executing from left to right, and each function should start with the pipe character `\|` . The functions are applied in the relevant order. It means that in the example below, first the `get` will be applied, and then the `match`. Functions have two components: 1. Name: `get`, `match`, `encode` 2. Parameters: see functions description below for additional info. Parameters are separated from the function name by a colon: Example: `{{ auth_object.stage1.response.headers \| get: '/Set-Cookie' }}` Example with chained functions: `{{ auth_object.stage1.response.headers \| get: '/Set-Cookie' \| match:/accessToken":"(.\*)"}/}}`

Supported pipes

get

Returns the value associated with the XPath, or undefined if there is none.

Parameters:

xpath - xpath string

Example: {{ auth_object.step1.response.headers | get: '/Set-Cookie' }}

match

Retrieves the result of matching a string against a regular expression.

Parameters:

regex - regular expression
group - number of the capture group (optional, default 1)

Example: {{ auth_object.step1.response.body | match:/accessToken":"(.*)"}/}}

encode

Encodes the value to some format.

Parameters:

format - base64, url or none (optional, default none)

Example: {{ auth_object.step1.response.body | encode: 'base64' }}

Generating data dynamically

Mock data

If you need to generate random data to use during the configuration of an authentication object, you can apply one of the following Faker.js data generators:

uuid
Example: {{ <$faker>.datatype.uuid }}
number
Example: {{ $faker.datatype.number }}

otpToken

Inserts an OTP (one-time password) with preconfigured parameters.

In order to use an OTP token you need to first configure it. To learn how to configure an OTP, see Creating Authentication page. Then you can use interpolation syntax to add it to your authorization flow.

Example: {{auth_object.otpToken}}