DEV Community

Cover image for How to Integrate Secret Managers in Bruno - A Complete Guide
Ganesh Patil
Ganesh Patil

Posted on

How to Integrate Secret Managers in Bruno - A Complete Guide

#bruno #security #devops #tutorial

Bruno is an open-source, native API client built for developers who want speed, privacy, and control. It's the fastest-growing API client in its space — and v4 is the release where it stops being just a request tool and starts being the development platform your whole team can build on.

Every non-trivial API has credentials. Database passwords, API keys, OAuth client secrets, tokens — they are everywhere. The natural instinct is to paste them into environment variables or .env files and move on. That works for a single developer, but it breaks down quickly when teams grow and security requirements tighten.

secret-managers

The real challenges show up when you ask:

  • How do we rotate a credential? If the API key is hardcoded in fifty collection files across ten developers' machines, rotating it means a manual update round-trip to every person on the team.
  • How do we onboard a new engineer? Sharing a .env file over Slack or email means the credential has now escaped the vault before it ever reached Bruno.
  • How do we audit who used what? When a key leaks, you need to know which systems were using it. Environment files have no audit trail.
  • How do we enforce least-privilege? Not every developer needs production credentials. Most need staging. A few need prod. Secret managers enforce this at the identity level — Bruno just reads what it is allowed to read.

This is why engineering teams adopt dedicated secret managers like HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault. They centralise credential storage, enforce access control, provide audit logs, and support automatic rotation — all without secrets ever touching a developer's file system.

Bruno v4 connects directly to all three, so your collections can pull live credentials at runtime without anyone ever copy-pasting a secret.

What Changed in Bruno v4


Breaking changes in v4 — read before upgrading.

In the app:

  • Secret Manager configuration has moved out of secrets.json and into environment files (.bru / environment.yml) under a new externalSecrets block.
  • Secret Manager is now configured from the Environment UI, not from Collection Settings.
  • Opening a collection with a secrets.json in the Bruno app triggers automatic migration. No manual step needed.
  • If secrets.json is marked read-only, migration will fail. Bruno shows a "start afresh" state and you will need to re-enter the configuration manually in the Environment UI.
  • The {{$secrets.name.keyname}} variable syntax is deprecated. The new syntax is {{name.keyname}}. Old syntax still resolves in v4 but is marked with a deprecation underline in the editor. Removal is planned for the next major release (at least 6 months away). A one-click in-app migration tool will ship in v4.2.0.

In the CLI:

  • The CLI does not auto-migrate. If it finds secrets.json without an externalSecrets block in the environment file, it prints a warning and continues without secrets.
  • Fix: open the collection in the Bruno app first, let the migration run, then commit the updated environment file.
  • Secret manager credentials are now passed via --secrets-env-file <path> instead of --env-var.
  • AWS Secrets Manager and Azure Key Vault are now supported in the CLI (HashiCorp Vault was the only option in v3).

Setting Up HashiCorp Vault

HashiCorp Vault is the most widely used open-source secret manager. Bruno supports both Vault Server (self-hosted or enterprise) and HCP Vault (HashiCorp Cloud Platform).

Step 1 — Add the provider in Preferences

  1. Open Bruno and go to Preferences → Secrets Manager.
  2. Click + Add Secret Manager.
  3. Select HashiCorp Vault Server as the provider type.
  4. Choose your authentication method:
    • Token — a static Vault token. Simplest option; good for local development.
    • App Role — a Role ID and Secret ID pair. Best for CI/CD and automated pipelines.
    • LDAP — username and password via an LDAP/Active Directory-backed Vault.
  5. Enter the Vault server URL (e.g. http://localhost:8200 for local, or your hosted URL).
  6. Enter the credentials for the chosen auth method.
  7. Click Test Connection, then Add.

hashicorp-vault

For HCP Vault, select HashiCorp Vault Cloud instead and provide your Client Credentials and project details.

Step 2 — Attach secrets to an environment

  1. Open your collection and go to Environments.
  2. Select the environment you want to add secrets to (e.g. Production).
  3. Open the External Secrets tab.
  4. Select your Vault account from the list.
  5. Enter a Name (the alias you'll use in requests, e.g. db) and a Path (the Vault path, e.g. secret/data/db).
  6. Click Fetch Secrets. The secret keys and values populate automatically.

hashicorp-vault-2

Step 3 — Reference secrets in requests 

{{db.password}}
{{db.username}}
Enter fullscreen mode Exit fullscreen mode

Use these in any URL, header, body, or auth field. Bruno resolves them at runtime from the fetched secret.

Step 4 — Run with the CLI

Export your Vault credentials directly from Preferences → Secrets Manager → hover the account → Export as .env. Then run:

# Token auth
bru run collection/ --env Production --env-var authToken=your-vault-token

# AppRole auth
bru run collection/ --env Production \
  --env-var roleId=your-role-id \
  --env-var secretId=your-secret-id
Enter fullscreen mode Exit fullscreen mode

Setting Up AWS Secrets Manager

AWS Secrets Manager is the native secret store for AWS workloads. It supports automatic rotation, fine-grained IAM policies, and is deeply integrated with RDS, Lambda, ECS, and other AWS services.

Step 1 — Add the provider in Preferences

  1. Open Bruno and go to Preferences → Secrets Manager.
  2. Click + Add Secret Manager.
  3. Select AWS Secrets Manager as the provider type.
  4. Choose your auth mode:
    • Manual — enter credentials directly.
    • AWS CLI — uses your active AWS CLI session (aws configure or environment variables).
  5. If using Manual, enter:
    • Access Key ID
    • Secret Access Key
    • Session Token (optional — only for temporary/assumed-role credentials)
    • Region (e.g. us-east-1)
  6. Click Test Connection, then Save.

aws-secret-manager

Step 2 — Attach secrets to an environment

  1. Open your collection and go to Environments.
  2. Select the target environment and open the External Secrets tab.
  3. Select your AWS account from the list.
  4. Enter a Name (alias, e.g. apiCredentials) and the AWS Secret Name or ARN (e.g. prod/api-key or the full ARN).
  5. Click Fetch Secrets.

aws-secret-manager-2

Step 3 — Reference secrets in requests 

{{apiCredentials.api_key}}
{{apiCredentials.client_id}}
Enter fullscreen mode Exit fullscreen mode

The key names match the JSON keys inside the AWS secret.

Step 4 — Run with the CLI

Export credentials from Preferences → Export as .env, or create a dotenv file manually:

BRUNO_AWS_ACCESS_KEY_ID=ABKIEXAMPLE
BRUNO_AWS_SECRET_ACCESS_KEY=wJxlxKEY
BRUNO_AWS_SESSION_TOKEN=Fwoz...   # optional
BRUNO_AWS_REGION=us-east-1
Enter fullscreen mode Exit fullscreen mode

Then run:

bru run collection/ --env Production --secrets-env-file ./secrets.env
Enter fullscreen mode Exit fullscreen mode

Setting Up Azure Key Vault

Azure Key Vault is Microsoft's managed secret, key, and certificate store. It integrates with Azure Active Directory for identity-based access control and supports both interactive (az login) and Service Principal authentication.

Step 1 — Add the provider in Preferences

  1. Open Bruno and go to Preferences → Secrets Manager.
  2. Click + Add Secret Manager.
  3. Select Azure Key Vault as the provider type.
  4. Choose your auth method:
    • Manual (Service Principal) — enter Tenant ID, Client ID, and Client Secret.
    • Azure CLI — uses your active az login session. No credentials to enter.
  5. If using Manual, enter:
    • Name — a label for this account (e.g. Production Vault)
    • Tenant ID — your Azure AD tenant ID
    • Client ID — the application (client) ID of your Service Principal
    • Client Secret — the secret value for that Service Principal
  6. Click Test Connection, then Add.

azure-secret-manager

Step 2 — Attach secrets to an environment

  1. Open your collection and go to Environments.
  2. Select the target environment and open the External Secrets tab.
  3. Select your Azure Key Vault account.
  4. Enter a Name (alias, e.g. paymentSecrets) and the Vault Name (the name of your Azure Key Vault instance, e.g. my-company-vault).
  5. Click Fetch Secrets.

azure-secret-manager-2

Step 3 — Reference secrets in requests 

{{paymentSecrets.stripe-key}}
{{paymentSecrets.webhook-secret}}
Enter fullscreen mode Exit fullscreen mode

The key names match the secret names inside your Azure Key Vault.

Step 4 — Run with the CLI

Service Principal:

BRUNO_AZURE_TENANT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BRUNO_AZURE_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
BRUNO_AZURE_CLIENT_SECRET=your-client-secret
Enter fullscreen mode Exit fullscreen mode

Azure CLI (existing az login session):

BRUNO_AZURE_AUTH_METHOD=cli
Enter fullscreen mode Exit fullscreen mode

Then run:

bru run collection/ --env Production --secrets-env-file ./secrets.env
Enter fullscreen mode Exit fullscreen mode

Team Workflow Tips

Keep secrets.env out of version control.
Add it to .gitignore. Store it in your team's CI/CD secret store (GitHub Actions secrets, GitLab CI variables, AWS Parameter Store, etc.) and write it to a temp file at runtime.

Use the Export as .env shortcut.
Once a provider is configured in Preferences → Secrets Manager, hover any account and click Export as .env. The file is ready to pass to --secrets-env-file immediately — no manual transcription required.

One environment file per deployment stage.
Each environment (Dev, Staging, Production) has its own externalSecrets block. Point Dev at a low-privilege Vault path; point Production at the real secrets. Developers without production IAM access cannot fetch prod secrets even if they have the collection.

Migrate old $secrets references now.
Search your collection for $secrets and update to the {{name.keyname}} syntax. A one-click migration tool will be available in v4.2.0, but doing it earlier reduces noise in the editor.

Conclusion

Managing secrets well is one of the unglamorous but essential parts of API development at scale. Rotating credentials, onboarding new engineers securely, and running automated tests in CI without secrets leaking into logs these are solved problems, but only if the tooling cooperates.

Bruno v4 connects your collections directly to the secret managers your team already uses. HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault are all first-class providers, both in the app and in the CLI. Configuration lives alongside your environments in version-controlled files, and credentials never touch your collection source.

Explore the full documentation:

Top comments (0)