Collection Settings

Configure collection-level settings for headers, auth, scripts, tests, variables, and more

Collection Settings in Bruno allow you to configure options that apply to all requests in a collection. Settings are managed through the CollectionSettings component and stored in the collection.bru file.

Accessing Collection Settings

1. Open Collection Actions

   Click the three-dot menu next to your collection name in the sidebar.

2. Select 'Settings'

   Choose “Settings” from the dropdown menu.

3. Navigate Between Tabs

   Use the tabs to configure different aspects of your collection.

The CollectionSettings component provides multiple tabs, each managing specific configuration:

Overview

Collection metadata and documentation

Headers

Default HTTP headers for all requests

Vars

Collection-level variables

Auth

Collection-wide authentication

Script

Pre-request and post-response scripts

Tests

Collection-level test suite

Presets

URL and request presets

Proxy

HTTP/HTTPS proxy configuration

Client Certificates

SSL/TLS client certificates

Protobuf

Protocol Buffers for gRPC

Overview Tab

The Overview component displays collection metadata and documentation.

Collection Documentation

From the test suite (bruno-tests/collection/collection.bru):

docs {
  # bruno-testbench 🐶
  
  This is a test collection that I am using to test various functionalities around bruno
}

Use the docs section to provide an overview of your API collection, including purpose, authentication requirements, and usage guidelines.

Headers Tab

The Headers component allows you to configure HTTP headers that will be sent with all requests in the collection.

Configuration

key · string

Header name (e.g., “User-Agent”, “X-API-Version”)

value · string

Header value. Supports variable interpolation: {{variable}}

enabled · boolean · default: true

Toggle to enable/disable headers without deleting them

Example

From the test suite:

collection.bru

headers {
  check: again
  token: {{collection_pre_var_token}}
  collection-header: collection-header-value
}

Header Count Indicator

The Headers tab shows the number of active headers:

From CollectionSettings component

<div className={getTabClassname('headers')} role="tab" onClick={() => setTab('headers')}>
  Headers
  {activeHeadersCount > 0 && <sup className="ml-1 font-medium">{activeHeadersCount}</sup>}
</div>

Common collection-level headers include API version headers, custom user agents, or tracking headers that should be sent with every request.

Vars Tab

The Vars component manages collection-level variables that can be set and retrieved in scripts.

Variable Types

Pre-Request Variables

Variables available before the request is sent.

vars:pre-request {
  collection_pre_var: collection_pre_var_value
  collection_pre_var_token: {{request_pre_var_token}}
  collection-var: collection-var-value
}

Post-Response Variables

Variables set after receiving the response (typically set via scripts).

// In post-response script
bru.setVar('response_time', res.responseTime);
bru.setVar('last_user_id', res.body.id);

Variable Scope

Collection Variables

Accessible throughout the entire collection. Set with bru.setVar() and retrieved with bru.getVar().

Environment Variables

Environment-specific values. Set with bru.setEnvVar() and retrieved with bru.getEnvVar().

Request Variables

Request-specific variables that don’t persist beyond the request.

Active Vars Count

The Vars tab displays the count of enabled variables:

const activeVarsCount = requestVars.filter((v) => v.enabled).length + responseVars.filter((v) => v.enabled).length;

{activeVarsCount > 0 && <sup className="ml-1 font-medium">{activeVarsCount}</sup>}

Auth Tab

The Auth component configures authentication that applies to all requests set to “Inherit” mode.

Supported Auth Types

All authentication modes are available at the collection level:

• AWS Sig v4 (awsv4)
• Basic Auth (basic)
• Bearer Token (bearer)
• Digest Auth (digest)
• NTLM Auth (ntlm)
• OAuth 2.0 (oauth2)
• WSSE Auth (wsse)
• API Key (apikey)

Configuration Example

collection.bru

auth {
  mode: bearer
}

auth:bearer {
  token: {{bearer_auth_token}}
}

Inheritance Info

The Auth tab displays this helpful message:

Configures authentication for the entire collection. 
This applies to all requests using the 'Inherit' option 
in the Auth tab.

Individual requests can override collection auth by selecting a different auth mode instead of “Inherit”.

See the Authentication guide for detailed information on each auth type.

Script Tab

The Script component allows you to configure collection-level pre-request and post-response scripts.

Collection Scripts Example

From the test suite:

collection.bru

script:pre-request {
  // Collection-level pre-request script
  const shouldTestCollectionScripts = bru.getVar('should-test-collection-scripts');
  if(shouldTestCollectionScripts) {
   bru.setVar('collection-var-set-by-collection-script', 'collection-var-value-set-by-collection-script');
  }
}

Script Execution Order

When a request is sent:

1. Collection pre-request script runs first
2. Folder pre-request script runs next (if applicable)
3. Request pre-request script runs last
4. HTTP request is sent
5. Request post-response script runs first
6. Folder post-response script runs next
7. Collection post-response script runs last

Use Cases for Collection Scripts

Token Refresh

// Check and refresh expired tokens
const tokenExpiry = bru.getEnvVar('token_expiry');
if (!tokenExpiry || Date.now() >= tokenExpiry) {
  // Trigger token refresh
  bru.setVar('needs_refresh', true);
}

Global Headers

// Add dynamic headers to all requests
req.setHeader('X-Request-ID', crypto.randomUUID());
req.setHeader('X-Client-Version', '1.0.0');
req.setHeader('X-Timestamp', Date.now().toString());

Logging

// Log all requests
console.log('Request:', req.method, req.url);
console.log('Environment:', bru.getEnvVar('environment'));

See the Scripts guide for more information.

Tests Tab

The Test component allows you to write tests that run for every request in the collection.

Collection-Level Tests Example

collection.bru

tests {
  // Run for all requests
  test("Response time is acceptable", function() {
    expect(res.responseTime).to.be.below(2000);
  });
  
  test("Status code is successful", function() {
    expect(res.status).to.be.at.least(200);
    expect(res.status).to.be.below(300);
  });
  
  test("Content-Type is JSON", function() {
    const contentType = res.getHeader('content-type');
    if (contentType) {
      expect(contentType).to.include('application/json');
    }
  });
}

When to Use Collection Tests

• Validate response time across all endpoints
• Check for required headers (CORS, security headers)
• Verify authentication is working collection-wide
• Ensure consistent error response formats

See the Tests guide for detailed testing information.

Presets Tab

The Presets component allows you to configure default request settings.

requestUrl · string

Default base URL for all requests. Can be overridden per request.

Preset Indicator

const hasPresets = presets && presets.requestUrl !== '';

{hasPresets && <StatusDot />}

Proxy Tab

The ProxySettings component configures HTTP/HTTPS proxy settings.

Proxy Configuration

hostname · string · required

Proxy server hostname or IP address

port · number · required

Proxy server port (e.g., 8080, 3128)

protocol · enum

Proxy protocol: http or https

auth · object

Optional proxy authentication:

• username: Proxy username
• password: Proxy password

Proxy Status Indicator

const proxyEnabled = proxyConfig.hostname ? true : false;

{Object.keys(proxyConfig).length > 0 && proxyEnabled && <StatusDot />}

Proxy settings apply to all requests in the collection. Ensure your proxy is properly configured to avoid request failures.

Client Certificates Tab

The ClientCertSettings component manages SSL/TLS client certificates for mutual authentication.

Certificate Configuration

domain · string · required

Domain or host for which the certificate applies (e.g., “api.example.com”)

certFilePath · string · required

Path to the client certificate file (.crt, .pem)

keyFilePath · string · required

Path to the private key file (.key, .pem)

passphrase · string

Optional passphrase if the private key is encrypted

Multiple Certificates

You can configure multiple client certificates for different domains:

From CollectionSettings

const clientCertConfig = collection.draft?.brunoConfig
  ? get(collection, 'draft.brunoConfig.clientCertificates.certs', [])
  : get(collection, 'brunoConfig.clientCertificates.certs', []);

{clientCertConfig.length > 0 && <StatusDot />}

Client certificates are useful for enterprise APIs that require mutual TLS authentication.

Protobuf Tab

The Protobuf component manages Protocol Buffer definitions for gRPC requests.

Protobuf Configuration

protoFiles · array

Array of .proto file paths relative to the collection directory

Example

Directory Structure

my-grpc-collection/
├── bruno.json
├── collection.bru
├── proto/
│   ├── user.proto
│   ├── product.proto
│   └── order.proto
└── requests/
    ├── get-user.bru
    └── create-order.bru

In Collection Settings → Protobuf:

Proto Files:
- proto/user.proto
- proto/product.proto
- proto/order.proto

Protobuf Status

{protobufConfig.protoFiles && protobufConfig.protoFiles.length > 0 && <StatusDot />}

See the Request Types guide for more on gRPC requests.

Settings Storage

All collection settings are stored in the collection.bru file at the root of your collection folder:

Complete Example

headers {
  User-Agent: Bruno/1.0
  X-API-Version: 2.0
}

auth {
  mode: bearer
}

auth:bearer {
  token: {{access_token}}
}

vars:pre-request {
  api_version: v2
  client_id: {{client_id}}
}

script:pre-request {
  // Set request timestamp
  req.setHeader('X-Timestamp', Date.now().toString());
}

script:post-response {
  // Log response time
  console.log('Response time:', res.responseTime, 'ms');
}

tests {
  test("Response is successful", function() {
    expect(res.status).to.be.at.least(200);
    expect(res.status).to.be.below(300);
  });
}

docs {
  # My API Collection
  
  This collection contains all endpoints for the Example API.
  
  ## Authentication
  Uses Bearer token authentication. Set `access_token` in your environment.
  
  ## Rate Limiting
  Rate limit: 1000 requests per hour
}

Inheritance Hierarchy

Bruno follows this inheritance hierarchy:

1. Collection Level

   Settings in collection.bru apply to all requests.

2. Folder Level

   Folder settings override collection settings for requests in that folder.

3. Request Level

   Request-specific settings override both folder and collection settings.

Inheritance Behavior by Setting Type

Headers

Additive: Collection headers + Folder headers + Request headers

Duplicate headers are overridden (request > folder > collection)

Auth

Override: Requests using “Inherit” use folder/collection auth. Other auth modes replace it entirely.

Scripts

Sequential: Collection scripts → Folder scripts → Request scripts (all run in order)

Tests

Cumulative: Collection tests + Folder tests + Request tests (all run)

Variables

Override: Request variables override folder/collection variables with same name

Best Practices

Use Collection Auth

Configure auth once at the collection level and use “Inherit” in requests to avoid duplication.

Set Common Headers

Put headers that apply to all requests (API version, user agent) at the collection level.

Leverage Collection Scripts

Use collection scripts for token refresh, request signing, or logging that applies globally.

Document Your Collection

Use the docs section to provide context, auth requirements, and usage guidelines.

Test Common Behavior

Use collection-level tests for response time, status codes, and header validations that apply everywhere.

Environment-Specific Settings

Use {{variables}} in collection settings and configure them per environment.

Next Steps

Authentication

Configure collection-level authentication

Scripts

Write collection-level scripts

Tests

Create collection-level tests

Environments

Manage environment variables