Environment Variables

Use environment variables to switch between development, staging, and production APIs without changing your requests.

What Are Environments

Environments in RestForge are named sets of key-value pairs that let you store configuration values outside of your requests. Instead of hardcoding URLs, tokens, or IDs in every request, you define them once as variables and reference them using the {{variable_name}} syntax.

Common use cases include:

Multi-stage APIs: Switch between development, staging, and production environments with a single tap
Team collaboration: Share collections with placeholder variables that teammates fill with their own credentials
Dynamic authentication: Store access tokens that expire and get refreshed via scripts
Client-specific testing: Test the same API with different client IDs, accounts, or tenant identifiers

For example, instead of changing https://api.dev.example.com to https://api.production.example.com in 20 different requests, you define {{base_url}} once and switch between environments.

Create an Environment

To create a new environment in RestForge:

Open Environments Screen

Tap the drawer menu icon (☰) in the top-left corner, then select Environments.

Add New Environment

Tap the + button in the bottom-right corner to create a new environment.

Name Your Environment

Enter a descriptive name like Development, Staging, or Production. Use names that make it obvious which environment you're testing against.

Save

Tap Save to create the environment. You can now add variables to it.

Tip: Create a template environment with placeholder values (e.g., {{YOUR_API_KEY}}) that you can duplicate and customize for different projects or team members.

Add Variables

Once you've created an environment, you can add key-value pairs to it:

Select Environment

From the Environments list, tap the environment you want to edit.

Add Variables

Tap Add Variable and enter the key and value. For example:

Key	Value
base_url	https://api.dev.example.com
api_key	dev_sk_1234567890abcdef
user_id	test_user_42

Naming Conventions

Follow these guidelines when naming variables:

Use snake_case for readability (e.g., base_url, not baseUrl)
Avoid spaces and special characters (except underscores)
Be descriptive: auth_token is better than token
Use prefixes for grouped variables: db_host, db_port, db_name

Security Note: Environment variables are stored locally on your device. If you enable Cloud Sync, they are encrypted before being synced. Never commit environment files with production credentials to public repositories.

Using {{variables}}

Reference environment variables anywhere in your requests using double curly braces: {{variable_name}}. RestForge will substitute the value at send time.

In Request URLs

Replace hardcoded domains and paths with variables:

URL {{base_url}}/api/v1/users/{{user_id}}

If base_url is https://api.dev.example.com and user_id is 42, this becomes:

https://api.dev.example.com/api/v1/users/42

In Headers

Use variables for authorization tokens, API keys, and custom headers:

Header	Value
Authorization	Bearer {{access_token}}
X-API-Key	{{api_key}}
X-Client-ID	{{client_id}}

In Request Body

Variables work in JSON, form data, and plain text bodies:

JSON Body { "username": "{{test_username}}", "email": "{{test_email}}", "tenant_id": "{{tenant_id}}" }

In Query Parameters

Add variables to query strings:

Key	Value
api_key	{{api_key}}
limit	{{page_size}}
offset	{{offset}}

Tip: Variables are resolved just before the request is sent. You can update variable values in scripts (see Variables in Scripts) and the changes will be reflected immediately in subsequent requests.

Switch Environments

RestForge lets you activate one environment at a time. When you switch environments, all {{variable}} references update instantly to use the new environment's values.

How to Switch

Open Environment Selector

Tap the environment name displayed in the top navigation bar (or No Environment if none is active).

Select Environment

Tap the environment you want to activate from the dropdown list. The selected environment becomes active immediately.

Example: Switching from Dev to Production

Suppose you have two environments:

Variable	Development	Production
base_url	https://api.dev.example.com	https://api.example.com
api_key	dev_key_12345	prod_key_abcdef

Your request URL is {{base_url}}/users. When you switch from Development to Production, the resolved URL changes from https://api.dev.example.com/users to https://api.example.com/users without editing the request itself.

Warning: Always verify which environment is active before sending requests. Accidentally sending test data to production or destructive operations to the wrong environment can cause serious issues. RestForge displays the active environment name in the UI to help prevent mistakes.

Variables in Scripts

RestForge supports JavaScript pre-request and post-response scripts that can read and write environment variables dynamically. This is essential for workflows like OAuth token refresh, session management, and data chaining between requests.

Reading Variables

Use pm.environment.get(key) to retrieve a variable value:

Pre-Request Script const apiKey = pm.environment.get('api_key'); const userId = pm.environment.get('user_id'); console.log('Testing with user:', userId);

Setting Variables

Use pm.environment.set(key, value) to create or update a variable:

Post-Response Script // Extract token from login response const response = pm.response.json(); const accessToken = response.data.access_token; // Store it in the environment pm.environment.set('access_token', accessToken); console.log('Access token saved:', accessToken);

Now all subsequent requests can use {{access_token}} in their Authorization headers without manual copying.

Deleting Variables

Use pm.environment.unset(key) to remove a variable:

Post-Response Script // Clear token on logout pm.environment.unset('access_token'); console.log('Access token cleared');

Example: Token Auto-Refresh

Here's a complete example of extracting an access token from a login response and using it in subsequent requests:

POST /auth/login - Post-Response Script // Parse the JSON response const jsonResponse = pm.response.json(); // Extract token and expiry const token = jsonResponse.access_token; const expiresIn = jsonResponse.expires_in; // seconds // Store in environment pm.environment.set('access_token', token); // Calculate expiry timestamp const expiryTime = Date.now() + (expiresIn * 1000); pm.environment.set('token_expiry', expiryTime); console.log('Token saved. Expires in:', expiresIn, 'seconds');

GET /users - Pre-Request Script // Check if token is expired const expiryTime = pm.environment.get('token_expiry'); if (!expiryTime || Date.now() > expiryTime) { console.warn('Token expired! Please login again.'); }

Learn More: For complete scripting documentation, see the Scripting Guide.

Global Variables

In addition to environment variables, RestForge supports global variables that persist across all environments. These are useful for values that don't change between dev/staging/prod, such as API version numbers or shared constants.

Setting Global Variables

Use pm.globals.set(key, value) in scripts:

Pre-Request Script // Set API version that applies everywhere pm.globals.set('api_version', 'v2'); // Set a request ID for tracing pm.globals.set('request_id', Date.now());

Reading Global Variables

Use pm.globals.get(key):

const apiVersion = pm.globals.get('api_version'); console.log('Using API version:', apiVersion);

In request URLs, use the same {{variable}} syntax. RestForge checks globals if the variable isn't found in the active environment.

Deleting Global Variables

pm.globals.unset('api_version');

Collection Variables

RestForge also supports collection-scoped variables via pm.collectionVariables.get(key). These are defined at the collection level and shared by all requests in that collection, but isolated from other collections.

Variable Scope Priority

When resolving {{variable_name}}, RestForge searches in this order:

Collection variables (highest priority)
Environment variables
Global variables (lowest priority)

If the same variable exists at multiple levels, the higher-priority value is used.

Best Practices

Use Environments for Configuration That Changes

Only put values in environments if they differ between dev, staging, and production. For constants that never change, use global or collection variables instead.

Never Hardcode Sensitive Values

Don't paste API keys, passwords, or tokens directly into request fields. Always use environment variables so you can:

Share collections without exposing credentials
Switch between test and production keys safely
Rotate credentials without editing every request

Use snake_case Naming

Consistent naming makes variables easier to read and autocomplete:

✅ base_url, api_key, user_id ❌ baseURL, apiKey, userId

Create a Template Environment

Create an environment called Template with placeholder values:

Key	Value
base_url	{{YOUR_API_URL}}
api_key	{{YOUR_API_KEY}}

Duplicate this template when starting new projects or onboarding team members. They can fill in their own values without guessing what variables are needed.

Document Required Variables

In your collection description or README, list all required environment variables with example values:

Collection Description Required environment variables: - base_url: API base URL (e.g., https://api.example.com) - api_key: Your API key (get it from Settings > API Keys) - user_id: Test user ID (use "test_user_42" for sandbox)

Prefix Environment-Specific Values

For clarity, consider prefixing values that are environment-specific:

Variable	Development	Production
env_name	development	production
base_url	https://api.dev.example.com	https://api.example.com
db_host	localhost	db.production.example.com

Then in scripts, you can check pm.environment.get('env_name') to conditionally log or skip certain operations.

Combine with Collections

Organize related requests into collections and use environments to configure them. For example:

Collection: "E-commerce API v2"
Environments: Development, Staging, Production
Workflow: Test new features in Development, validate in Staging, smoke test in Production

Learn more in the Collections Guide.

Next Steps: Now that you understand environment variables, explore Scripting to automate workflows, or learn how to sync environments across devices.