Dynamic parameter values

APIsec can resolve a parameter value at scan time instead of holding a fixed value you have to maintain. Rather than configuring a parameter with 15, you configure it with @random.val.int.1.20; when the scan starts, APIsec resolves the token and uses the result.

Use dynamic values when a fixed one would break testing — an idempotency key your API rejects if reused, a field that must be unique on every run, or a date that has to stay in the future.

Scope: per scan or per request

Every token comes in two forms, and the only difference is how often it resolves.

Token	Scope	Where it resolves
@random.val.<type>	Per scan	Variable, parameter, and body values. Resolves once, when the scan assembles its requests, and the same value is reused for every request in that scan.
@random.req.<type>	Per request	Header values only. Resolves again for each individual HTTP request.

Use @random.val when a value must be random per run but consistent across the requests in that run. Use @random.req for a header that must be unique on every request, such as an idempotency key or a correlation ID.

warning

@random.req resolves in header values only. Placed anywhere else — a query parameter, a path parameter, a request body field — it is not an error and not substituted: the literal text @random.req.int.1.100 is sent to your API. Use @random.val outside headers.

A third construct references a value you already configured rather than generating one:

{{@Var.<type>.<name>}}

Syntax

@random.val.<type>[.<x>[.<y>]]
@random.req.<type>[.<x>[.<y>]]

• x and y are optional non-negative whole numbers controlling string length or numeric range. Negative values are not accepted.
• A bare token must be the entire field value. To place one inside a longer string, wrap it in {{ }} — see Embedding a token in a string.

Basic types

Type	Generates	JSON type
string	An alphanumeric string (letters and digits only)	String
integer	A whole number	Number
int	Alias of integer	Number
long	A whole number	Number
double	A fractional number	Number
boolean	true or false	Boolean
uuid	A random UUID, such as f47ac10b-58cc-4372-a567-0e02b2c3d479	String

The JSON type matters when a variable is injected into a JSON request body: @random.val.integer produces 42, not "42". Likewise @random.val.boolean produces true, not "true".

Length and range suffixes

Suffix	Meaning
None	For string, 1–32 characters; for numeric types, a value between 1 and 32
.x	Exactly x — for string, exactly x characters; for numeric types, always the value x
.x.y	Between x and y inclusive. If x is greater than y, the engine swaps them

• A single number sets both the minimum and the maximum, so the result is exact — @random.val.string.10 is always 10 characters, not up to 10, and @random.val.integer.7 always produces 7.
• For string, the numbers are lengths in characters. Lengths above 250 are clamped to 250.
• For integer, int, long, and double, the numbers are the value range, not lengths. @random.val.integer.10.99 produces an integer between 10 and 99. For double, the value is fractional, roughly within the given range.
• boolean and uuid take no suffix. A numeric suffix on these types is parsed and then ignored — @random.val.uuid.5 still produces a UUID.

Generated identity and business data

Data	Per-scan token	Example output
Email	@random.val.email	dquof04c@example.test
Name	@random.val.name	Grace Wilkes
First name	@random.val.firstname	Grace
Last name	@random.val.lastname	Wilkes
Phone	@random.val.phone	+1-555-821-1097
Address	@random.val.address	123 Main St, Springfield
Company	@random.val.company	Acme Holdings

Replace val with req for a new value on every request.

Dates

@random.val.date.<expression>[.<format>]

The expression is relative to the date the scan runs on, so the result moves with the scan:

@random.val.date.today            → 27/08/2026
@random.val.date.today+7d         → 03/09/2026
@random.val.date.today-7d         → 20/08/2026
@random.val.date.today+30d        → 26/09/2026

Offsets accept these units, and can be chained (today+1y-1d):

Unit	Means
s	seconds
min	minutes
h	hours
d	days
w	weeks
mo	months
m	months, not minutes
y	years

warning

m means months. Use min for minutes. today+30m moves the date forward thirty months, not thirty minutes.

Append a format to control the output:

@random.val.date.today+7d.dd/MM/yyyy   → 03/09/2026
@random.val.date.today+7d.yyyy-MM-dd   → 2026-09-03
@random.val.date.today+7d.iso          → 2026-09-03T00:00:00Z

Output is UTC unless the format pattern explicitly encodes a time zone.

The format must match what the target API expects. If the API expects 2026-09-01T00:00:00Z and the token produces 01/09/2026, the API may return 400 Bad Request.

note

A 400 Bad Request does not by itself mean token resolution failed. The token may have resolved correctly and the target API rejected the resulting value because its format was incompatible. Inspect the generated request to tell the two apart.

Anchoring one date to another

A date can use another date parameter as its reference point, which is how you hold two dates in a fixed relationship instead of generating each independently.

Suppose an API takes coverStartDate and coverEndDate, and coverEndDate must always be one year minus one day after coverStartDate:

coverStartDate = @random.val.date.today.iso
coverEndDate   = @random.val.date.$coverStartDate+1y-1d.iso

$coverStartDate is the anchor, +1y adds a year, -1d subtracts a day, and .iso sets the format. When the scan starts, APIsec resolves coverStartDate first and then calculates coverEndDate from it.

The anchor must name an available date variable. If it cannot be resolved, the dependent expression cannot be calculated.

Timestamps

@random.val.ts              → 1776153600000
@random.val.ts.epoch_ms     → 1776153600000

epoch_ms is a format suffix on ts, not a token type of its own — there is no @random.val.epoch_ms.

Referencing an existing variable

{{@Var.<type>.<name>}}

For example, {{@Var.s.coverStartDate}} references an existing APIsec variable named coverStartDate. It does not generate a new value.

note

The referenced variable must exist in the applicable variable configuration. If it cannot be resolved, the literal reference may reach the target API and cause a validation error there.

Embedding a token in a string

A bare token must be the whole field value. To place one inside a longer string, wrap it in {{ }}:

P@ss{{@random.val.string.4.8}}1!   → P@ssKq7wJx3z1!
user-{{@random.val.uuid}}          → user-6463352d-69ca-4bbf-b652-754673d4904d

Without the braces the token is not substituted — user-@random.val.string is sent to the API as-is.

Embedding produces string output, so it is supported only for parameters declared as string, id, json, object, or map.

Validation at save time

APIsec validates a token when you save the parameter, checking it against the parameter's declared type and, where present, its OpenAPI format. An incompatible token is rejected with an error in the console before any scan runs.

Type compatibility

Token types	Accepted on parameters declared as
string, uuid, email, name, firstname, lastname, phone, address, company, date, ts	string, id, json, object, map
int, integer, long, double	integer, int, long, double, number, float, decimal
boolean	boolean

OpenAPI format

Type and format are separate. When a parameter declares an OpenAPI format, the token must match the format as well as the type, so check both columns before choosing one.

Parameter type	OpenAPI format	Compatible token
string	uuid	@random.val.uuid
string	date	@random.val.date.*
integer	int32	@random.val.int.*

What gets rejected

Value	Why it fails
@random.val.foobar	Unknown token type
@random.val.int.1.100 on a boolean parameter	Numeric token on a boolean parameter
@random.val.boolean on an integer parameter	Boolean token on a numeric parameter
@random.val.int.100.1	Minimum greater than maximum

Validation runs in the console. A token that reaches a scan without passing through it — an unrecognized type, for example — is not rejected at scan time; it resolves to a plain random string instead.

Token reference

Purpose	Per scan	Per request	Example
String	@random.val.string	@random.req.string	Kq7wJx3z
Integer	@random.val.int / @random.val.integer	@random.req.int / @random.req.integer	@random.val.int.1.100 → 42
Long	@random.val.long	@random.req.long	9876543210
Double	@random.val.double	@random.req.double	@random.val.double.1.100 → 42.57
Boolean	@random.val.boolean	@random.req.boolean	true
UUID	@random.val.uuid	@random.req.uuid	6463352d-69ca-4bbf-b652-754673d4904d
Email	@random.val.email	@random.req.email	dquof04c@example.test
Name	@random.val.name	@random.req.name	Grace Wilkes
First name	@random.val.firstname	@random.req.firstname	Grace
Last name	@random.val.lastname	@random.req.lastname	Wilkes
Phone	@random.val.phone	@random.req.phone	+1-555-821-1097
Address	@random.val.address	@random.req.address	123 Main St, Springfield
Company	@random.val.company	@random.req.company	Acme Holdings
Date	@random.val.date.*	—	@random.val.date.today+7d.dd/MM/yyyy → 03/09/2026
Timestamp	@random.val.ts.*	—	@random.val.ts.epoch_ms → 1776153600000
Existing variable	{{@Var.<type>.<name>}}	—	{{@Var.s.coverStartDate}} → 2026-08-27
Embedded token	{{@random.val.uuid}}	{{@random.req.uuid}}	user-6463352d-69ca-4bbf-b652-754673d4904d

Related

• Discover parameters — where parameter values are configured.
• Manage Headers — where per-request tokens are most often used.