Managing Hoppscotch Variable Scopes for Secure, Predictable API Requests

Desired Outcome

Configure and use Hoppscotch variables across global, environment, collection, and local scopes so that credentials and dynamic values resolve predictably, stay secret where required, and sync correctly in team workspaces.

Prerequisites

• Hoppscotch desktop or web app (v2024.10 or later) with a workspace open.
• Access to the Environments panel (gear icon) and Collection settings.
• For team sync: a Hoppscotch Cloud or self‑hosted workspace with admin rights to invite collaborators.
• Optional: hoppscotch-cli installed for headless runs.

Procedure

1. Create an environment with secret values

1. Open the Environments panel → New Environment → name it prod-api.
2. Add key‑value pairs:
   • baseUrl = https://api.example.com
   • apiKey = sk_live_abc123 → enable Secret toggle.
3. Activate the environment for the current tab (click the environment dropdown and select prod-api).

2. Define collection‑level defaults

1. Open a collection → Settings → Variables.
2. Add apiVersion = v2 and commonHeader = application/json.
3. Save. These values apply to every request in the collection unless overridden.

3. Use variables in a request

1. Create a new request: GET {{baseUrl}}/users.
2. Add header Authorization: Bearer {{apiKey}} and Accept: {{commonHeader}}.
3. Set the request path to /{{apiVersion}}/list.
4. Send the request. Verify in the Network tab that the resolved URL is https://api.example.com/v2/list and the Authorization header contains the secret value (masked in UI).

4. Override at runtime with a local variable (pre‑request script)

// Pre‑request script for the same request
hoppscotch.variables.set('baseUrl', 'https://staging.example.com', 'local');
console.log('Resolved baseUrl:', hoppscotch.variables.get('baseUrl'));

1. Add the script above to the request’s Pre‑request Script tab.
2. Send again. The console should log Resolved baseUrl: https://staging.example.com and the request URL must reflect the staging host, demonstrating local precedence over the environment value.

5. Chain values with post‑response scripts

// Post‑response script after a login request
const token = response.json().access_token;
hoppscotch.variables.set('authToken', token, 'local');

Subsequent requests in the same chain can reference {{authToken}} without storing the token in any persistent scope.

6. Share via team workspace

1. In the workspace settings, invite a collaborator (role Editor or Admin).
2. The collaborator sees the prod-api environment with apiKey masked.
3. When the collaborator updates baseUrl to a new endpoint, the change appears in your session within seconds (real‑time sync).

7. Export / import with secrets handling

1. Collection → Export → choose JSON. By default secret values are omitted.
2. Import the file into another workspace. The environment variables appear but apiKey is empty.
3. Manually re‑enter secrets or use the Import with secrets option (available only to workspace admins) to restore them.

8. Run headless with the CLI

# Run from a terminal with CLI installed
hoppscotch-cli run collection.json -e environment.json

• Ensure environment.json contains the same keys (non‑secret values). Secrets must be supplied via environment variables on the host (e.g., export HOPPS_API_KEY=sk_live_abc123) and referenced in the collection as {{apiKey}}.
• Exit code 0 and printed responses confirm variable resolution matches the UI.

Expected Checks

• Variable resolution: Open the Variables panel (eye icon) for a request; it lists resolved values with scope badges (global, env, collection, local). Confirm the highest‑precedence value is used.
• Secret masking: In the UI, secret fields show ••••••. In the Network tab, the actual value is sent; ensure you never log it via console.log.
• Scope precedence: After step 4, the Variables panel should show baseUrl with a local badge overriding the environment entry.
• Team sync: Edit an environment value as a collaborator and watch the change propagate without refresh.
• CLI parity: Compare the CLI output URL and headers with the UI request; they must match exactly.

Recovery Options

• Accidental secret exposure in logs: Clear the console, remove any console.log of secret variables, and rotate the compromised credential in the upstream service.
• Scope collision: Adopt a naming convention (e.g., env_baseUrl, coll_apiVersion, local_override) to avoid unintended shadowing. If a collision occurs, delete the offending local variable from the pre‑request script or rename it.
• Self‑hosted encryption key loss: Without ENCRYPTION_KEY secrets are stored plaintext. Rotate the key, then re‑enter all secret values; there is no automatic re‑encryption.
• WebSocket/SSE token expiry: Since variables are not re‑evaluated after handshake, implement a reconnect logic in a post‑response script that fetches a fresh token and re‑opens the connection.
• CLI OAuth limitation: For flows requiring user interaction, pre‑author a token using a client‑credentials grant and inject it via an environment variable before the CLI run.

Limitations & Practical Verification

• Variable names are case‑sensitive; {{API_KEY}} and {{api_key}} are distinct.
• The UI does not warn on duplicate names across scopes; always inspect the Variables panel before sending critical requests.
• Secrets are encrypted at rest only when the self‑hosted instance has a valid ENCRYPTION_KEY.
• To verify the whole chain, run the CLI with --verbose (if supported) and diff the resolved request against the UI’s Network tab.