API Testing: Environments
Overview
Use this page to add and manage the environments that API test flows run against. An environment is a saved target configuration: a base URL plus optional headers, allowed hosts, and variables, that a flow points at instead of hardcoding connection details into every flow. This keeps where a flow sends requests separate from what the flow does, so one flow definition can run against different hosts.
You typically create an environment before building a flow, since every flow needs a base URL to send requests to. Flows select an environment on API Testing: Flows, and scheduled runs of those flows on API Testing: Schedules use the same environment; results appear afterward in API Testing: Run History. Authentication is handled separately on API Testing: Auth Profiles; this page covers the connection details and reusable values instead.
This page lists every environment configured for the account, showing its name, base URL, and header/variable counts. From here you add a new environment, open an existing one to edit its base URL, headers, allowed hosts, or variables, or delete one you no longer need.
Key concepts
- Environment - A saved target configuration, a base URL plus optional headers and variables, that an API test flow runs against instead of a hardcoded connection. (related: API Testing: Flows)
- Variables - Named values scoped to an environment that flows can reference by name instead of hardcoding them in each request; a value can be marked secret so it stays masked until revealed.
- Allowed Hosts - A list of hostnames this environment's requests are permitted to reach, used together with Allow Private Ranges to control where flow requests can go.
- Headers - Static HTTP headers sent automatically with every request made against this environment, such as a fixed API key or content-type override. (related: API Testing: Auth Profiles)
When to use it
- Before building a new API test flow, to give it a base URL to send requests to.
- When you need to run the same flow against a different host, such as moving it from a staging host to a production one.
- When a target system requires a fixed header on every request, such as an API key.
- When you want to store reusable values, such as an account ID, that several flows can reference instead of repeating them.
- When you need to restrict which hosts a flow is allowed to reach for a given target.
- When an environment is no longer used and should be removed.
Before you begin
- Your role grants permission to manage API Testing environments; without it, Add Environment is hidden and the edit/delete icons are disabled. Role permissions are configured on Operations: Permissions.
- You know the base URL of the system the environment should target, for example a staging or production host.
- You have the header names/values, allowed hostnames, and variable names/values the environment needs, if any; they are entered directly on this page rather than imported.
Common workflows
Add a new environment
Persona: API test author
- Click Add Environment.
- Expect: The Add Environment dialog opens with empty Name, Base URL, Description, Headers, Allowed Hosts, and Variables fields.
- Enter a Name and a Base URL, then click Save.
- Expect: The dialog closes and a new row for the environment appears in the table with 0 headers and 0 variables.
Verify: The new environment's row is visible in the table with the name and base URL you entered, and it's selectable as a target when you build or edit a flow.
Add a header and a secret variable to an existing environment
Persona: Admin configuring shared credentials
- Click the Edit icon on the environment's row.
- Expect: The dialog opens pre-filled with that environment's current Name, Base URL, headers, allowed hosts, and variables.
- Click Add Header, enter a header name and value.
- Expect: A new header row appears in the dialog with the values you entered.
- Click Add Variable, enter a name and value, and check the secret option.
- Expect: A new variable row appears with its value masked behind an eye icon.
- Click Save.
- Expect: The dialog closes; the environment's row in the table now shows an increased Headers count and an increased Variables count.
Verify: The Headers and Variables counts on the environment's row have each increased by one, confirming the new header and variable were saved.
Remove an environment that's no longer used
Persona: Admin cleaning up unused configuration
- Click the Delete icon on the environment's row.
- Expect: A Delete Environment confirmation dialog opens.
- Confirm the deletion.
- Expect: The dialog closes and the environment's row no longer appears in the table.
Verify: The environment no longer appears in the table, and flows that previously targeted it can no longer select it.
Steps
Step 1
Open Environments from the API Testing section.
Expected result: The page loads a table listing the environments already configured for the account, showing each one's name, base URL, and how many headers and variables it has.
Reviewing the existing environments is the starting point before adding a new one or editing an existing one.
- Add Environment sits in the top-right corner as the primary action.
- The Headers and Variables columns show counts only; open an environment's Edit dialog to see the actual values.
- Each row's Actions column holds an Edit (pencil) and Delete (trash) icon.
Field reference
| Field | Purpose | Format / Validation | Required | Default |
|---|---|---|---|---|
| Name | The display name used to identify this environment wherever you select one for a flow. Choose a name that distinguishes it from other environments, such as the host or purpose it represents, for example Puppis lunch-peak replay. | text | Yes | - |
| Base URL | The host flow requests are sent to when a flow targets this environment. Point it at a staging host while testing changes, and at a production host only when you intend to run real traffic against it. | URL | Yes | - |
| Description | An optional free-text note describing what the environment is for. It is shown only in this dialog and is not sent with requests or used by flows. | text | No | - |
| Header name / value | A custom HTTP header sent automatically with every request made against this environment, such as a fixed API key or content-type. Add one entry per header; the more you add, the more headers every flow run against this environment carries. | text pair (header name, value) | No | - |
| Allowed Hosts | Restricts which hostnames this environment's requests may reach. Leave it empty if you don't need to limit destinations; add entries to confine requests to a known set of hosts. | list of hostnames | No | empty |
| Allow Private Ranges | Turn this on to let requests from this environment reach private or internal IP ranges; leave it off to keep requests limited to public hosts. Enable it only when the environment genuinely targets an internal system. | toggle (on/off) | No | - |
| Variable name / value | A reusable named value flows can reference instead of hardcoding it in each request. Check the secret option for a variable to mask its value behind an eye icon until you choose to reveal it, which is useful for tokens or passwords. | text pair plus secret checkbox | No | - |
Column reference
| Column | What it shows | How to read it |
|---|---|---|
| Name | Identifies the environment in the list. | Read it to identify which saved target configuration a row represents. |
| Base URL | Shows the host the environment's requests are sent to. | Compare it against the system you intend to test to confirm you've selected the right environment. |
| Headers | Shows how many custom headers this environment has configured. | A higher number means more headers are automatically attached to every request this environment sends; 0 means none are configured. |
| Variables | Shows how many reusable variables this environment has configured. | A higher number means more reusable values are available to flows that target this environment; 0 means none are configured. |
| Actions | Holds the Edit and Delete controls for the row. | A disabled icon with a tooltip means your role can't perform that action on this environment. |
Controls reference
Add Environment
Opens a dialog to create a new environment.
When to use: When a flow needs a target that doesn't exist yet.
Side effects: Read-only until you click Save; opening it makes no change to existing data.
Edit (row icon)
Opens the same dialog pre-filled with the environment's base URL, description, headers, allowed hosts, and variables, ready to change.
When to use: When you need to update a URL, add or remove a header, or change a variable.
Side effects: Read-only until you click Save; if your role can read but not change environments, this opens a read-only View dialog instead and Save is withheld.
Delete (row icon)
Opens a confirmation dialog for deleting that environment.
When to use: When an environment is no longer used by any flow.
Side effects: Read-only on its own; disabled with a tooltip if your role can't change environments.
Save
Creates a new environment or writes your changes to an existing one, then closes the dialog.
When to use: After filling in the required Name and Base URL and any optional headers, hosts, or variables.
Side effects: Mutating: creates or updates the environment on the server; the table refreshes to show the new or updated row.
Delete Environment (confirm)
Permanently removes the environment.
When to use: When you've confirmed no flow still needs this environment.
Side effects: Mutating: deletes the environment from the server; the row disappears from the table immediately and the action cannot be undone.
Add Header
Adds a blank header name/value row inside the dialog.
When to use: When the target system needs an extra fixed header on every request.
Side effects: Non-persistent until you click Save.
Remove header (trash icon)
Removes a header row from the dialog.
When to use: When a previously added header is no longer needed.
Side effects: Non-persistent until you click Save.
Add (Allowed Hosts)
Adds a hostname to the Allowed Hosts list in the dialog.
When to use: When you want to restrict this environment's requests to specific hosts.
Side effects: Non-persistent until you click Save.
Remove allowed host (trash icon)
Removes a hostname from the Allowed Hosts list.
When to use: When a restriction is no longer needed.
Side effects: Non-persistent until you click Save.
Add Variable
Adds a blank variable name/value row inside the dialog.
When to use: When a flow needs a reusable value stored on the environment.
Side effects: Non-persistent until you click Save.
Remove variable (trash icon)
Removes a variable row from the dialog.
When to use: When a stored value is no longer needed.
Side effects: Non-persistent until you click Save.
Show/hide secret (eye icon)
Toggles whether a secret variable's value is masked or shown in the dialog.
When to use: When you need to verify a stored secret value before saving.
Side effects: Read-only; it does not change the stored value.
Retry
Asks the server to load the environments list again after a failed read.
When to use: When the table failed to load and shows an error instead of rows.
Side effects: Read-only; it does not change any data.
Verify the result
After opening Environments, the table lists every environment configured for the account, each row showing its name, base URL, header count, and variable count. If you just added or edited one, its row reflects the new name, base URL, and updated header/variable counts. If your role can manage environments, the edit and delete icons on each row are active and Add Environment is visible; if not, Add Environment is hidden and the row icons are disabled. An empty table, with no rows at all, means no environment has been created yet for this account.
Troubleshooting
- Symptom: Add Environment is missing from the page. Fix: Your role doesn't have permission to manage environments; ask an administrator to grant it on Operations: Permissions.
- Symptom: Clicking the row icon opens a read-only dialog titled View, with Save missing. Fix: Your role can read environments but not change them; request edit permission from an administrator.
- Symptom: Save is blocked and the dialog shows "Name is required." or "Base URL is required." Fix: Fill in both the Name and Base URL fields; both are mandatory before the environment can be saved.
- Symptom: The Delete icon is disabled on a row. Fix: Your role lacks permission to delete environments, as the tooltip confirms; contact an administrator to change your role's grants.
- Symptom: The table shows an error instead of rows. Fix: Click Retry to reload the list; if it keeps failing, confirm you still have access to API Testing.
- Symptom: A flow can't find a header or variable you expect. Fix: Open the environment the flow targets and check its Headers/Variables counts; a count of 0 means nothing was saved for that environment.
Related articles
- Next step: API Testing: Flows - Flows select an environment as the base URL target when you build or run them.
- See also: API Testing: Auth Profiles - Auth profiles supply the authentication a flow uses alongside an environment's headers.
- See also: API Testing: API Sources - API sources can inform which base URLs the flows targeting an environment will call.
- Next step: API Testing: Schedules - Scheduled runs execute flows against the environment you configure here.
- Prerequisite: Operations: Permissions - Your role needs environment-management grants before Add Environment and the row actions appear.