Separating Secrets from Shared Collections in Insomnia with Local and Git‑Backed Vaults

Problem

Teams often share API request collections in Insomnia, but the same workspace can contain secrets such as OAuth tokens or API keys. If the workspace is synced to a cloud or Git repository, those secrets risk exposure. The goal is to keep sensitive data out of the shared collection while still versioning the API contracts and non‑secret configuration.

Requirements

• Insomnia v10 or later (local‑first workspaces and Git‑backed vault support).
  Note: Verify the exact terminology in your version’s settings; older releases used "Workspace Settings > Sync" while newer ones use "Workspace Settings > Vault".
• Git repository with branch protection and code‑review workflow.
• Team members with read access to the Git repo and local‑only workspace permissions.
• Optional: CI pipeline to lint workspace JSON for accidental secret commits.

Minimal Design

1. Local‑Only Workspace – All secrets live here. The workspace is marked as "Local‑Only" so Insomnia never pushes it to any remote or cloud service. 2. Git‑Backed Remote Vault – Stores shared collections, environment templates, and request scripts. The remote vault is linked to the same Git repo but is configured to ignore environment files that contain secrets. 3. Environment Inheritance – Create a base environment in the remote vault for host, port, and non‑secret tokens. Each local workspace inherits from this base and adds its own secret variables. 4. Request Chaining – Use a short‑lived token request that runs before the main request, storing the result in a temporary environment variable that is not persisted.

Trust & Data Boundaries

• Local Vault is the sole trust boundary for secrets. Nothing in this workspace is pushed to Git or the cloud.
• Remote Vault contains only non‑secret data. All environment files that reference secret variables are excluded via a .gitignore entry or by using Insomnia’s "Exclude from Sync" flag.
• Shared collections reside in the remote vault, enabling version control, code reviews, and branch protection.
• Plugins or external schemas are considered untrusted; they should be vetted before import.

Operational Checks

1. Verify Local‑Only Setting

   # In Insomnia, open the workspace > Settings > Vault
   # Ensure "Sync" is disabled and the workspace is marked "Local‑Only".
   

2. Confirm Secrets Are Not in Git

   git clone https://repo.example.com/api-workspaces.git
   cd api-workspaces
   git log --all --pretty=format:"%h %s" | grep -i "secret"
   # No commits containing secret values should appear.
   

3. Validate Environment Inheritance

   # In Insomnia, open a request and look at the "Environment" dropdown.
   # The resolved environment should show the base values plus any local overrides.
   # Use the "Preview" button to ensure secret variables are masked.
   

4. Check Request Chaining

   # Run the token request first; the response script should set
   # env.short_lived_token = response.body.access_token.
   # Verify the token is only present in the current session.
   

Failure Modes & Mitigation

• Accidental Commit of Secret – If a secret is accidentally committed, the Git audit log shows the commit. Mitigation: enforce a pre‑commit hook that scans for patterns like "api_key" or "secret".
• Merge Conflict in Environment File – Large or binary collections can cause difficult merges. Mitigation: keep environments small and modular; use separate files for each environment.
• Cloud Sync Enabled by Accident – Cloud sync can replicate request history and cookies. Mitigation: disable cloud sync in the workspace settings and audit the account’s sync settings periodically.
• Plugin Exploitation – Imported plugins can execute code. Mitigation: only import from trusted sources and review plugin code.

When to Change the Design

• If the team needs to share secrets (e.g., a shared API key for a third‑party service) across all members, you may shift to a dedicated secret store (e.g., Vault, AWS Secrets Manager) and reference it via environment variables.
• If the collection grows beyond a few dozen requests, consider splitting into multiple workspaces to keep merge conflicts manageable.
• When CI/CD pipelines require automated request runs, you may expose short‑lived tokens in a secure CI secret store and inject them via environment variables.

Concrete Example

Assume we have a production API that requires an OAuth client secret. We want to keep the secret out of the shared collection.

Step 1 – Create Local‑Only Workspace

# In Insomnia, File > New Workspace
# Name: Prod API
# Type: Local‑Only
# Save the workspace.

Step 2 – Add Secret Environment

# In the local workspace, create an environment named "Prod".
# Add variable:
#   client_secret: REPLACE_WITH_SECRET
# Mark the environment as "Exclude from Sync".

Step 3 – Create Remote Vault

# In Insomnia, File > New Workspace
# Name: Shared API
# Type: Git‑Backed
# Link to https://repo.example.com/api-workspaces.git
# In the remote workspace, create an environment template "Base":
#   host: api.example.com
#   port: 443
#   auth_token: <non‑secret>

Step 4 – Inherit Environments

# In the local workspace, set the base environment to inherit from the remote "Base".
# The local environment then adds the client_secret.

Step 5 – Request Chaining

# Create a request "Get Token".
# In the response script, add:
// env.short_lived_token = response.body.access_token;
# Create a second request "Call Service" that uses ${short_lived_token}.

Practical Verification

• Open the shared collection in a local‑only workspace and run the "Get Token" request. The console should show the token being set.
• Check the environment preview for the "Call Service" request – the token should appear as a placeholder, not a literal secret.
• Clone the Git repo and inspect the environment JSON – it should not contain the client_secret.

Summary

By combining a local‑only workspace for secrets, a Git‑backed remote vault for shared collections, and environment inheritance, teams can keep sensitive API credentials out of shared code while still benefiting from version control, code review, and collaboration. Regular operational checks and awareness of failure modes ensure the design remains secure and maintainable.