Environment Variables and Secrets: Hoppscotch vs a Local Vault

Environment variables provide a convenient way to store non-secret values such as base URLs for an API client. However, storing real access tokens in a synced collection can pose security risks, as credentials can be exported, shared, or committed to version control. To enhance security, it is advisable to maintain configuration in environment variables while keeping secrets in a local vault or the operating system's credential store. These secrets are then injected at request time and never written into the collection file.

While Hoppscotch and similar tools use environment variables to switch between local, staging, and production values, this mechanism becomes problematic when it is also used to store bearer tokens and API keys. A collection, designed to be shared, is not an ideal place for sensitive data. Teams that treat configuration and secrets as the same value type often discover the issue only when a token is exported or included in a screenshot.

The main concerns with storing secrets in a collection include:

1. Exporting and sharing: A collection containing tokens can be exported and unintentionally shared, exposing the secret.

2. Version control: If the configuration is saved in a repository, even a private one, the secret becomes part of the history and difficult to remove completely.

3. Screen and log exposure: Tools that render resolved headers may display tokens in screenshots or include them in exported request logs.

4. Long-lived, shared tokens: Using a single environment value for multiple team members makes it challenging to rotate access, as everyone must be updated simultaneously.

To address these issues, it is recommended to keep non-sensitive values in the environment and resolve secrets from a local vault or credential store. At request time, the client should read the token from the vault or an environment variable held outside the shared artifact. If the tool supports it, mark variables as secrets to mask them and prevent inclusion in exports. If the tool lacks this capability, keep the token entirely outside the tool and inject it manually.

The goal is to ensure that the shared artifact, when exported, contains no credentials, even if the rest of the file is visible. By separating the client's environment from a local vault or credential store, you maintain a contract for base URLs and non-secret values in the source-controlled artifact while keeping secrets out of it. This approach allows for per-user or per-role tokens, making it easier to manage access and revoke permissions without editing shared environment variables.

In essence, treat documented authentication schemes as part of the contract, while the actual credentials remain separate, local secrets. This separation ensures that API requests generated from the spec can reference authentication schemes and resolve the actual token from local environment variables or a vault at the boundary, rather than embedding it within the shared collection.