Variables

Variables let you write {{placeholder}} somewhere in a request and have the value come from the active environment at send time. This page covers the syntax, the rules, and the masking behavior.

The {{placeholder}} syntax

Anywhere a value can appear in a request, you can write {{name}} and it will be replaced by the value of the variable named name in the active environment. The substitution happens once, at send time, on the server.

{{baseUrl}}/users/{{userId}}
Authorization: Bearer {{token}}

Whitespace inside the braces is allowed:

{{ baseUrl }}     ===     {{baseUrl}}
{{ my.key }}      ===     {{my.key}}

Allowed characters in name: letters, digits, underscore, hyphen, and dot. Names are case-sensitive.

Resolution rules

• Only the active environment's variables are considered.
• Disabled variables (enabled: false) are ignored.
• A {{placeholder}} with no matching enabled variable causes the request to fail. The error message lists every missing key.
• The same placeholder used multiple times in one request is resolved to the same value.
• Substituted values are not re-scanned for {{}} after substitution. A variable whose value contains {{foo}} will not be resolved a second time.
• Variables are not interpolated into request names, folder names, collection names, or environment names — only into the fields of the request itself (see Variable scope).

Where variables apply

Variables work in:

• The URL
• Header keys and values
• Query parameter keys and values
• Auth fields: Bearer token, Basic username/password, API key name/value, OAuth token URL/client ID/client secret/scope/access token
• The raw body of a Raw mode body
• URL-encoded field keys and values
• Multipart text field keys and values

For more, see Variable scope.

The secret flag

A variable marked secret behaves like any other variable at send time, but:

• In the environments sheet, the value is masked behind •••••••• until you click the eye icon.
• In the request area, secrets that have been written into the request's Authorization header (via the Auth tab) are also masked.
• In history, the value is replaced with ••••••••.
• In normal workspace exports (the export endpoint and the .rewind archive without the includeSecrets flag), the value is omitted. A normal export is the default.

To export the real values, use the explicit-confirmation flag in the export endpoint or in the archive download. Both prompt the user before they include secrets.

The secret flag is a UI/storage concern. The server does not refuse to send a secret; it just stores and surfaces it carefully.

Common patterns

A baseUrl for each backend

Create one environment per backend:

Environment	baseUrl
Local	http://localhost:3000
Staging	https://staging.example.com
Production	https://api.example.com

All requests in your collection use {{baseUrl}}/users/42. Switch environments to retarget the same request.

Per-user tokens

Put a token variable in each environment, marked secret. Switch the environment to switch identities. The token is never persisted in the request itself.

Feature flags

{
  "userId": "{{userId}}",
  "features": ["{{flagA}}", "{{flagB}}"]
}

Variables work inside JSON bodies as long as the body mode is Raw.

Limitations

• No default values: a missing variable is an error, not an empty string. If you need a fallback, define the variable in every environment.
• No nested resolution: {{a}} whose value is prefix-{{b}} will not resolve {{b}} in turn.
• No type coercion: every value is a string. If a server expects an integer, your variable's value should be a stringified integer.
• No dynamic expressions: you cannot write {{baseUrl}}/users/{{ userId + 1 }} and have arithmetic happen.

What's next?

• Environments — the broader picture: how environments are created, switched, and deleted
• Variable scope — exactly which fields are substituted
• Code generation — variables are preserved in generated snippets