Dynamic Parameter Values
Dynamic Parameter Values allow APIsec to resolve parameter values at scan time instead of requiring users to maintain a static point-in-time value.
For example, instead of configuring a parameter with:
15
you can configure it with:
@random.val.int.1.20
When the scan starts, APIsec resolves the token to a valid value and uses the resolved value in the scan.
How Dynamic Parameter Values Work
Configure parameter
↓
Enter dynamic token
↓
Save parameter
↓
APIsec validates the token against the parameter type/format
↓
Scan starts
↓
Token is resolved
↓
Resolved value is substituted into the request
↓
HTTP request is sent
Inspect the generated request when validating a dynamic parameter. A target API error does not necessarily mean that token resolution failed.
Token Scopes
| Token | Scope | Behavior |
|---|---|---|
@random.val.* | Per scan | Resolves once when the scan starts and is reused throughout that scan |
@random.req.* | Per request | Resolves again for every HTTP request |
Use @random.val.* when the same generated value must remain consistent throughout a scan. Use @random.req.* when a new value is required for every request.
Supported Tokens
Basic Random Values
String
@random.val.string
Per-request variant:
@random.req.string
Example:
@random.val.string
→ Kq7wJx3z
Integer
@random.val.int
@random.val.integer
Example:
@random.val.integer
→ 84
A range can be supplied:
@random.val.int.1.100
Example:
@random.val.int.1.100
→ 42
Per-request variant:
@random.req.int.1.100
Long
@random.val.long
Example:
@random.val.long
→ 9876543210
Per-request:
@random.req.long
Double
@random.val.double
Example:
@random.val.double
→ 57.38
Per-request:
@random.req.double
Boolean
@random.val.boolean
Generates either true or false.
Per-request:
@random.req.boolean
For a boolean parameter, the generated value is intended to be used as a boolean rather than as the string "true" or "false".
Example:
{
"repeat_request_if_failed": true
}
UUID
@random.val.uuid
Example:
@random.val.uuid
→ 6463352d-69ca-4bbf-b652-754673d4904d
Per-request:
@random.req.uuid
Generated Email, Name, Contact, and Business Data
| Data | Per-scan token | Example output |
|---|---|---|
@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 |
For each of these, replace val with req to generate a new value for every HTTP request.
Dynamic Dates
Dynamic dates use:
@random.val.date.<expression>[.<format>]
Example:
@random.val.date.today
→ 27/08/2026
With an offset:
@random.val.date.today+7d
→ 03/09/2026
With an offset and format:
@random.val.date.today+7d.dd/MM/yyyy
→ 03/09/2026
For an ISO-formatted date/time:
@random.val.date.today+7d.iso
→ 2026-09-03T00:00:00Z
The per-request form is:
@random.req.date.<expression>[.<format>]
Relative Dates
Example:
@random.val.date.today+7d.dd/MM/yyyy
This means today plus seven days, formatted as dd/MM/yyyy.
The result depends on the date on which the scan runs. For example, if the scan date is 20/08/2026, the result would be 27/08/2026.
Common examples:
@random.val.date.today
@random.val.date.today+1d
@random.val.date.today+7d
@random.val.date.today-7d
@random.val.date.today+30d
Date Formatting
Example:
@random.val.date.today+7d.yyyy-MM-dd
can produce:
2026-08-27
The output format must be compatible with the format expected by the target API.
For example, if an API expects:
2026-09-01T00:00:00Z
but the token produces:
01/09/2026
the target API may return 400 Bad Request.
A 400 Bad Request does not by itself mean that dynamic-value resolution failed. The token may have resolved successfully while the target API rejected the resulting value because its format was incompatible.
Date Anchors
Date anchors allow one dynamic date parameter to be used as the reference point for another date parameter.
This is useful when two or more dates need to maintain a fixed relationship. Instead of generating each date independently, you can define one date as the anchor and calculate other dates relative to it.
Example
Suppose an API requires two parameters:
coverStartDate
coverEndDate
The requirement is:
coverEndDate must always be one year minus one day after `coverStartDate`.
Configure the parameters as follows:
coverStartDate = @random.val.date.today.iso
coverEndDate = @random.val.date.$coverStartDate+1y-1d.iso
Here:
- $coverStartDate is the anchor.
- +1y adds one year.
- -1d subtracts one day.
- .iso specifies the output format.
The anchor must refer to an available date variable. If the referenced anchor cannot be resolved, the dependent date expression cannot be calculated correctly.
When the scan starts, APIsec first resolves coverStartDate and then calculates coverEndDate.
Dynamic Timestamps
Timestamp values use:
@random.val.ts
Example:
@random.val.ts
→ 1776153600000
A format can also be specified:
@random.val.ts.epoch_ms
Per-request variants are:
@random.req.ts
@random.req.ts.epoch_ms
@random.val.ts.* is resolved once per scan, while @random.req.ts.* is resolved for every request.
Existing Variable References
Existing variable references use:
{{@Var.<type>.<name>}}
Example:
{{@Var.s.coverStartDate}}
This references an existing APIsec variable named coverStartDate; it does not generate a new random value.
The referenced variable must be available in the applicable APIsec variable configuration. If it cannot be resolved, the literal reference may reach the target API and cause an API validation error.
Per-Scan Determinism
@random.val.* tokens are resolved once when a scan starts and the resolved value is reused throughout that scan.
For example:
@random.val.int.1.100
might resolve to:
42
If five endpoints use that value in the same scan:
Endpoint 1 → 42
Endpoint 2 → 42
Endpoint 3 → 42
Endpoint 4 → 42
Endpoint 5 → 42
A new scan can resolve the token to a different value.
Per-Request Freshness
@random.req.* tokens are resolved again for every HTTP request.
For example:
@random.req.uuid
could produce different values for different requests.
This differs from:
@random.val.uuid
which remains stable throughout a scan.
Choosing the Scope
| Requirement | Token |
|---|---|
| Same value throughout a scan | @random.val.* |
| New value for every request | @random.req.* |
| Use an existing configured variable | {{@Var.<type>.<name>}} |
Save-Time Type and Format Validation
Dynamic tokens are validated when the parameter is saved.
APIsec checks the configured token against the parameter's declared type and, when available, its OpenAPI format. Incompatible tokens should be rejected with a clear UI error before the scan starts.
Type Compatibility
String-compatible tokens
These token types are string-compatible:
string
uuid
email
name
firstname
lastname
phone
address
company
date
ts
They are accepted on parameters declared as:
string
id
json
object
map
Numeric tokens
Numeric token types include:
int
integer
long
double
They are accepted on:
integer
int
long
double
number
float
decimal
Boolean
@random.val.boolean
is accepted only on:
boolean
For example:
Parameter:
repeat_request_if_failed
Type:
boolean
Value:
@random.val.boolean
is valid.
OpenAPI Format Validation
The parameter's declared type and OpenAPI format are separate pieces of information.
When an OpenAPI format is present, the dynamic token must match the format as well as the type.
Examples:
| Parameter type | OpenAPI format | Compatible token |
|---|---|---|
| string | uuid | @random.val.uuid |
| string | date | @random.val.date.* |
| integer | int32 | @random.val.int.* |
Therefore, users should check both the Type and Format columns before selecting a dynamic token.
Embedded Dynamic Tokens
Dynamic tokens can be embedded inside a larger string.
Embedded tokens must use {{ }}.
Example:
P@ss{{@random.val.string.4.8}}1!
could resolve to:
P@ssKq7wJx3z1!
Another example:
user-{{@random.val.uuid}}
could resolve to:
user-6463352d-69ca-4bbf-b652-754673d4904d
Embedded dynamic tokens are supported only for:
string
id
json
object
map
because embedding produces string output.
Whole-value tokens do not need {{ }}:
@random.val.uuid
When a token is embedded in other text, use:
{{@random.val.uuid}}
Invalid Dynamic Values
Unknown Token
This is invalid:
@random.val.foobar
Unknown token types are rejected.
Invalid Type
For a boolean parameter:
Type:
boolean
this is invalid:
@random.val.int.1.100
because an integer token is incompatible with a boolean parameter.
Likewise, an integer parameter should not use:
@random.val.boolean
Invalid Bounds
This is invalid:
@random.val.int.100.1
because the minimum is greater than the maximum.
Complete Token Reference
| Purpose | Per-scan | Per-request | Example |
|---|---|---|---|
| String | @random.val.string | @random.req.string | @random.val.string → Kq7wJx3z |
| Integer | @random.val.int | @random.req.int | @random.val.int.1.100 → 42 |
| Integer | @random.val.integer | @random.req.integer | @random.val.integer.1.100 → 57 |
| Long | @random.val.long | @random.req.long | @random.val.long → 9876543210 |
| Double | @random.val.double | @random.req.double | @random.val.double.1.100 → 42.57 |
| Boolean | @random.val.boolean | @random.req.boolean | @random.val.boolean → true |
| UUID | @random.val.uuid | @random.req.uuid | @random.val.uuid → 6463352d-69ca-4bbf-b652-754673d4904d |
@random.val.email | @random.req.email | @random.val.email → dquof04c@example.test | |
| Name | @random.val.name | @random.req.name | @random.val.name → Grace Wilkes |
| First name | @random.val.firstname | @random.req.firstname | @random.val.firstname → Grace |
| Last name | @random.val.lastname | @random.req.lastname | @random.val.lastname → Wilkes |
| Phone | @random.val.phone | @random.req.phone | @random.val.phone → +1-555-821-1097 |
| Address | @random.val.address | @random.req.address | @random.val.address → 123 Main St, Springfield |
| Company | @random.val.company | @random.req.company | @random.val.company → Acme Holdings |
| Date | @random.val.date.* | @random.req.date.* | @random.val.date.today+7d.dd/MM/yyyy → 03/09/2026 |
| Timestamp | @random.val.ts.* | @random.req.ts.* | @random.val.ts.epoch_ms → 1776153600000 |
Existing variable references remain:
{{@Var.<type>.<name>}}
Quick Reference
| Need | Token | Example output |
|---|---|---|
| Random integer | @random.val.int.1.100 | 42 |
| New integer for every request | @random.req.int.1.100 | 57 |
| Boolean | @random.val.boolean | true |
| UUID | @random.val.uuid | 6463352d-69ca-4bbf-b652-754673d4904d |
@random.val.email | dquof04c@example.test | |
| Date seven days from today | @random.val.date.today+7d.dd/MM/yyyy | 03/09/2026 |
| Anchor-relative date | @random.val.date.$coverStart+1y-1d.iso | 2027-08-26T00:00:00Z |
| Timestamp | @random.val.ts.epoch_ms | 1776153600000 |
| Embedded dynamic value | user-{{@random.val.uuid}} | user-6463352d-69ca-4bbf-b652-754673d4904d |
| Existing variable | {{@Var.s.coverStartDate}} | 2026-08-27 |
Best Practices
- Check the parameter's Type before selecting a token.
- Check the OpenAPI Format when one is available.
- Use
@random.val.*when consistency across a scan is required. - Use
@random.req.*when every HTTP request needs a new value. - Use
{{@Var.<type>.<name>}}when referencing an existing configured variable. - Use
{{ }}for embedded tokens. - Inspect the generated request when testing runtime behavior.
- Separate token-resolution failures from target-API validation failures.
- Evaluate date expectations relative to the scan time.
- Output is UTC unless the format pattern explicitly encodes a time zone.
Summary
Dynamic Parameter Values replace static parameter values with values generated or resolved at scan time.
The key behaviors are:
@random.val.*resolves once per scan.@random.req.*resolves once per HTTP request.{{@Var.<type>.<name>}}references an existing variable.- Date tokens support relative expressions and anchors.
- Timestamp tokens support supported timestamp formats.
- Dynamic values are validated against the parameter's type and OpenAPI format at save time.
- Embedded tokens must use
{{ }}. - Embedded tokens produce string output and therefore require a string-compatible parameter type.
- Unknown tokens and invalid bounds are rejected at save time.
- Output is UTC unless the format explicitly specifies a time zone.
- A target API error such as
400 Bad Requestdoes not necessarily mean dynamic-value resolution failed; inspect the generated request and distinguish token resolution from API-side validation.