API Testing: Environments

Updated

API Testing: Environments

Overview

Use this page to create and manage API testing environments. An environment is a named set of connection details, a base URL, headers, and variables, that an API test flow runs against. Environments let you point the same flow at different targets, such as production, staging, or acceptance, without editing the flow itself.

Environments sit between the systems under test and the flows you build in API Testing: Flows. You typically create an environment once you know the base URL of a target, and reference any credentials it needs from Configuration: Credential Profiles. Once defined, an environment is selected when running or scheduling a flow, and its headers and variables are substituted into every request the flow sends.

This page lists every environment in a table showing its Base URL and the number of headers and variables it carries. From here you create a new environment, edit an existing one's base URL, headers, variables, and allowed hosts, or delete one that's no longer needed. A toast surfaces credentials nearing expiry so you can reissue them before flow runs start failing authentication.

Key concepts

  • environment - A named combination of a base URL, headers, and variables that an API test flow runs against. Switching the environment a flow uses repoints it at a different target without editing the flow. (related: API Testing: Flows)
  • header - A static name/value pair sent with every request made against the environment, such as a fixed content-type or API key.
  • variable - A named placeholder that a flow substitutes with the environment's value at run time, letting the same flow run unchanged across different environments. Variables can be marked Secret to mask their value. (related: API Testing: Flows)
  • Allowed Hosts - A list of hostnames an environment's requests are permitted to reach. Adding a host allows it; removing a host blocks requests to it.
  • credential - An authentication token or secret, such as a Bearer token, issued and reissued separately from the environment that references it. (related: Configuration: Credential Profiles)

When to use it

  • Before running an API test flow for the first time against a new target host
  • When a flow needs to run unchanged against production, staging, or acceptance by switching only the environment
  • When a credential or token used by an environment is expiring and needs to be reissued
  • When restricting which hostnames a flow's requests are allowed to reach
  • When reviewing how many headers or variables an environment carries before editing it
  • When removing an environment that's no longer referenced by any flow

Before you begin

  • Know the base URL of the system under test you want to add as an environment
  • Have a role with the grant to create and change environments; without it, Add Environment is hidden and Edit opens as a read-only View (configured in Operations: Permissions)
  • Any token or secret the environment's headers or variables reference should already exist in Configuration: Credential Profiles

Common workflows

Create a new environment

Persona: API test operator

  1. Select Add Environment above the table.
    • Expect: The Add Environment dialog opens with empty Name and Base URL fields.
  2. Enter a Name such as Puppis lunch-peak replay and the target's Base URL, then use Add Header or Add Variable for any values the flow needs.
    • Expect: Each added row appears in the dialog's Headers or Variables list.
  3. Select Save.
    • Expect: The dialog closes and the new environment appears as a row in the table, with Header and Variable counts matching what you entered.

Verify: The new environment's Name and Base URL show in the table, and the Headers/Variables counts match the rows added in the dialog.

Restrict and secure an environment's variables

Persona: API testing admin

  1. Select the Edit pencil icon on an existing environment's row.
    • Expect: The dialog opens pre-filled with that environment's Base URL, headers, allowed hosts, and variables.
  2. Add a host under Allowed Hosts and turn on the Secret checkbox for any variable holding a token or password.
    • Expect: The host appears as a tag in the list, and the secret variable's value becomes masked with a show/hide icon.
  3. Select Save.
    • Expect: The dialog closes and the table's Variables count reflects the environment's current variables.

Verify: Reopening Edit on the same environment shows the added host under Allowed Hosts and the variable still marked Secret with its value masked by default.

Steps

Step 1

Open Environments under API Testing.

Expected result: The page loads the environment table with Name, Base URL, Headers, Variables, and Actions columns, listing existing environments such as Demo appliance (Production), LoadGen Demo - Api, and Orders API (Acceptance); a Credentials expiring notice appears because the Orders API token is due to expire in 4 days.

Reviewing the list is the starting point before creating, editing, or auditing the environments flows run against.

  • The Credentials expiring toast names the expiring token and where to reissue it.
  • Each row's Actions column holds Edit (pencil) and Delete (trash) icons. API Testing: Environments - step 1

Field reference

Field Purpose Format / Validation Required Default
Name Identifies the environment in the table and in the environment picker used when running or scheduling a flow. text Yes -
Base URL The root address flow requests are sent against. Changing the Base URL repoints every flow that selects this environment, without changing the flow itself, so use it to move a flow between production, staging, or acceptance targets. text (URL) Yes -
Description Free-text note to record what the environment is for, such as the system under test or team that owns it. text No empty
Headers Static name/value pairs sent with every request made against this environment. Use a header instead of a variable when the value never changes between runs, such as a fixed content-type or API key. key-value list No empty list
Allowed Hosts Restricts which hostnames requests from this environment may reach. Add a host to permit it; remove it to block requests to that host. tag list No empty
Allow Private Ranges Turn this on to let the environment's requests resolve to private or internal IP ranges, useful when the target is on an internal network such as a demo appliance. Leave it off to block requests from reaching private IP space. toggle No off
Variables Named placeholders a flow substitutes with this environment's values at run time, letting one flow run unchanged across environments with different values. Mark a variable Secret to mask its value in the UI. key-value list with Secret flag No empty list

Column reference

Column What it shows How to read it
Name The environment's display name. Match this against the environment name you select when running or scheduling a flow.
Base URL The root address flow requests go to when this environment is selected. Confirm it points at the intended system under test before running a flow against it.
Headers Count of static headers configured on the environment. 0 means no custom headers are sent; open Edit to see or change them.
Variables Count of variables configured on the environment. A non-zero count means flows using this environment rely on substituted values; open Edit to review them.
Actions Row-level Edit and Delete icons. A disabled icon with a tooltip means your role cannot change environments.

Controls reference

Add Environment

Opens the Add Environment dialog with empty Name, Base URL, Description, Headers, Allowed Hosts, and Variables fields.

When to use: Use it to define a new target for API test flows to run against.

Side effects: No change until Save is selected; only shown to roles with the create grant for environments.

Edit

Opens the same dialog pre-filled with the selected environment's Base URL, headers, allowed hosts, and variables.

When to use: Use it to change an existing environment's details.

Side effects: Mutating once Save is selected; for a role without the change grant it opens the same dialog as a read-only View, with every field disabled and Save withheld.

Delete

Opens a delete confirmation for the selected environment.

When to use: Use it to remove an environment that's no longer used by any flow.

Side effects: Mutating: confirming permanently removes the environment and its headers and variables; disabled with an explanatory tooltip for roles without the change grant.

Add Header

Adds a new empty header name/value row to the dialog.

When to use: Use it when the environment needs an additional static header.

Side effects: Local to the open dialog until Save is selected.

Add (Allowed Hosts)

Adds the host typed into the field to the Allowed Hosts list.

When to use: Use it to restrict requests to a specific hostname.

Side effects: Local to the dialog until Save is selected.

Add Variable

Adds a new empty variable name/value row to the dialog.

When to use: Use it when a flow needs an additional runtime placeholder value.

Side effects: Local to the dialog until Save is selected.

Show/hide secret

Toggles whether a variable marked Secret displays its value in plain text or masked.

When to use: Use it to confirm a secret variable's value before saving.

Side effects: Read-only, display-only toggle; does not change the stored value.

Save

Persists the Add/Edit dialog's changes.

When to use: Use it after entering or changing an environment's details.

Side effects: Mutating: creates or updates the environment and closes the dialog; disabled and withheld for read-only roles.

Close (toast)

Dismisses the Credentials expiring notice.

When to use: Use it once you've noted or acted on the expiring credential.

Side effects: Read-only: only hides the toast, does not reissue or otherwise affect the credential.

Retry

When to use: Use it when the table reports it could not load the environments.

Side effects: Read-only: re-fetches data, makes no changes to environments.

Verify the result

When an environment is created or edited successfully, it appears as a row in the table with the Name and Base URL you set, and the Headers and Variables columns show counts matching what you configured in the dialog. Reopening Edit on that row shows the same values you saved, including any Allowed Hosts and secret-masked variables. If the row is missing after Save, or the counts don't match what you entered, reopen Edit and confirm the Base URL and that each header or variable row had both a name and a value. If Edit opens as a read-only View with Save withheld, your role doesn't have the grant to change environments.

Troubleshooting

  • Symptom: No Add Environment button appears above the table. Fix: your role lacks the grant to create environments; ask an admin to update your permissions in Operations: Permissions.
  • Symptom: The Edit icon opens a dialog with every field disabled and Save unavailable. Fix: this is expected when your role can view but not change environments; request the change-environments grant.
  • Symptom: The Delete icon is grayed out with a tooltip saying your role cannot change environments. Fix: same as Edit, request the change grant from an admin rather than trying again.
  • Symptom: The Credentials expiring toast names a token used by one of your environments. Fix: reissue the credential under Configuration → Credential Profiles before it expires, or flow runs using that environment will start failing authentication.
  • Symptom: The table shows it could not load the environments. Fix: select Retry; if it keeps failing, the environment list is unreachable and existing rows (if previously loaded) stay visible while you try again.
Was this article helpful?
0 out of 0 found this helpful