Authentication

Bruno supports multiple authentication methods that can be configured at the request, folder, or collection level. Auth settings are managed through the Auth component in the request pane and CollectionSettings/Auth for collection-level configuration.

Authentication Modes

Bruno supports the following authentication types, as defined in RequestPane/Auth/AuthMode:

Basic Auth

Username and password authentication using HTTP Basic Auth.

Bearer Token

Token-based authentication using the Authorization header.

OAuth 2.0

Industry-standard OAuth 2.0 with multiple grant types.

API Key

Custom API key in header, query param, or cookie.

AWS Sig v4

Amazon Web Services signature version 4 authentication.

Digest Auth

More secure alternative to Basic Auth using MD5 hashing.

NTLM Auth

Windows NT LAN Manager authentication.

WSSE Auth

WS-Security authentication for SOAP services.

Setting Authentication Mode

Authentication can be configured at three levels:

Request Level
Folder Level
Collection Level

Set authentication for a specific request in the Auth tab of the request pane.

Open Request Auth Tab

Click on the “Auth” tab in the request pane.

Select Auth Mode

Use the AuthMode dropdown to select an authentication type.

Configure Details

Fill in the required fields for the selected auth method.

Set default authentication for the entire collection in Collection Settings.The CollectionSettings/Auth component provides collection-wide auth configuration:

Info Message

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

Basic Authentication

The BasicAuth component handles HTTP Basic Authentication:

Configuration

username

string

required

Username for authentication. Supports variable interpolation: {{username}}

password

string

required

Password for authentication. Supports variable interpolation: {{password}}

Example in .bru File

meta {
  name: Basic Auth Protected Endpoint
  type: http
}

get {
  url: {{host}}/api/protected
  body: none
  auth: basic
}

auth:basic {
  username: {{username}}
  password: {{password}}
}

assert {
  res.status: eq 200
}

Using Script for Basic Auth

From the test suite (bruno-tests/collection/auth/basic/via script/Basic Auth 200.bru):

meta {
  name: Basic Auth 200
  type: http
}

post {
  url: {{host}}/api/auth/basic/protected
  body: json
  auth: none
}

assert {
  res.status: eq 200
  res.body.message: Authentication successful
}

script:pre-request {
  const username = "bruno";
  const password = "della";
  
  const authString = `${username}:${password}`;
  const encodedAuthString = require('btoa')(authString);
  
  req.setHeader("Authorization", `Basic ${encodedAuthString}`);
}

Use pre-request scripts when you need dynamic Basic Auth credentials or custom encoding logic.

Bearer Token

The BearerAuth component handles Bearer token authentication:

Configuration

token

string

required

Bearer token value. Supports variable interpolation: {{access_token}}

Example

From the test suite:

bruno-tests/collection/auth/bearer/via auth/Bearer Auth 200.bru

meta {
  name: Bearer Auth 200
  type: http
}

get {
  url: {{host}}/api/auth/bearer/protected
  body: none
  auth: bearer
}

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

assert {
  res.status: 200
  res.body.message: Authentication successful
}

script:post-response {
  bru.setEnvVar("foo", "bar");
}

Bearer tokens are automatically added to the Authorization header as Bearer {token}.

OAuth 2.0

The OAuth2 component provides comprehensive OAuth 2.0 support with multiple grant types:

Grant Types

The GrantTypeSelector component supports four grant types:

Password Credentials
Authorization Code
Implicit
Client Credentials

Resource Owner Password Credentials flow.

accessTokenUrl

string

required

Token endpoint URL

username

string

required

Resource owner username

password

string

required

Resource owner password

clientId

string

OAuth client ID

clientSecret

string

OAuth client secret

scope

string

Requested scopes (space-separated)

OAuth 2.0 Configuration Options

credentialsPlacement

enum

default:"body"

Where to send client credentials:

body: In request body (default)
header: In Authorization header

tokenPlacement

enum

default:"header"

Where to include the access token:

header: Authorization header (default)
query: Query parameter

tokenHeaderPrefix

string

default:"Bearer"

Prefix for token in Authorization header (e.g., “Bearer”, “Token”)

tokenQueryKey

string

default:"access_token"

Query parameter name when tokenPlacement is “query”

OAuth 2.0 Example

meta {
  name: OAuth 2.0 Protected API
  type: http
}

get {
  url: {{api_url}}/protected/resource
  body: none
  auth: oauth2
}

auth:oauth2 {
  grantType: client_credentials
  accessTokenUrl: https://auth.example.com/oauth/token
  clientId: {{oauth_client_id}}
  clientSecret: {{oauth_client_secret}}
  scope: read:users write:users
  tokenPlacement: header
  tokenHeaderPrefix: Bearer
}

API Key Authentication

The ApiKeyAuth component allows flexible API key placement:

Configuration

key

string

required

API key parameter name (e.g., “X-API-Key”, “api_key”)

value

string

required

API key value. Supports variables: {{api_key}}

placement

enum

required

Where to send the API key:

header: HTTP header
query: Query parameter
cookie: Cookie

Examples

auth:apikey {
  key: X-API-Key
  value: {{api_key}}
  placement: header
}

AWS Signature v4

The AwsV4Auth component provides AWS authentication:

Configuration

accessKeyId

string

required

AWS Access Key ID. Use {{aws_access_key_id}} for security.

secretAccessKey

string

required

AWS Secret Access Key. Use {{aws_secret_access_key}} for security.

sessionToken

string

Optional session token for temporary credentials.

service

string

required

AWS service name (e.g., “s3”, “execute-api”, “lambda”).

region

string

required

AWS region (e.g., “us-east-1”, “eu-west-1”).

Example

meta {
  name: AWS API Gateway Request
  type: http
}

get {
  url: https://api-id.execute-api.us-east-1.amazonaws.com/prod/resource
  body: none
  auth: awsv4
}

auth:awsv4 {
  accessKeyId: {{aws_access_key_id}}
  secretAccessKey: {{aws_secret_access_key}}
  sessionToken: {{aws_session_token}}
  service: execute-api
  region: us-east-1
}

Never commit AWS credentials to version control. Always use environment variables or secure secret management.

Digest Authentication

The DigestAuth component provides more secure authentication than Basic Auth:

Configuration

username

string

required

Username for Digest authentication

password

string

required

Password for Digest authentication

Example

meta {
  name: Digest Auth Request
  type: http
}

get {
  url: {{host}}/digest-protected
  body: none
  auth: digest
}

auth:digest {
  username: {{digest_username}}
  password: {{digest_password}}
}

NTLM Authentication

The NTLMAuth component provides Windows NTLM authentication:

Configuration

username

string

required

Windows username (may include domain: DOMAIN\username)

password

string

required

Windows password

Example

auth:ntlm {
  username: DOMAIN\{{windows_user}}
  password: {{windows_password}}
}

WSSE Authentication

The WsseAuth component provides WS-Security authentication:

Configuration

username

string

required

WSSE username

password

string

required

WSSE password

Authentication Inheritance

Bruno supports authentication inheritance through the collection hierarchy:

Set Collection-Level Auth

Configure authentication in Collection Settings → Auth tab.

Use 'Inherit' in Requests

In request Auth tab, select “Inherit” mode to use collection/folder auth.

Override When Needed

Individual requests can override inherited auth by selecting a different mode.

Inheritance Example

Collection Structure

API Collection (Auth: Bearer Token)
├── Users Folder (Auth: Inherit)
│   ├── Get Users (Auth: Inherit) ← Uses collection Bearer token
│   └── Create User (Auth: Inherit) ← Uses collection Bearer token
└── Public Folder (Auth: None)
    └── Health Check (Auth: None) ← No authentication

The collection-level auth in collection.bru:

auth {
  mode: bearer
}

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

Using Variables for Security

Environment Variables

Store sensitive credentials in environment variables:

environments/production.json

{
  "api_key": "sk_live_...",
  "oauth_client_secret": "secret_...",
  "aws_secret_access_key": "..."
}

.gitignore Environments

Add environment files to .gitignore to prevent committing secrets:

.gitignore

environments/*.json
!environments/example.json

Runtime Variable Setting

Use pre-request scripts to fetch tokens dynamically:

// Fetch token from auth service
const authRes = await axios.post('https://auth.example.com/token', {
  client_id: bru.getEnvVar('client_id'),
  client_secret: bru.getEnvVar('client_secret')
});

bru.setVar('access_token', authRes.data.access_token);

Best Practices

Use Inheritance

Configure auth at the collection or folder level to avoid duplication and ensure consistency.

Store Secrets Securely

Never hardcode credentials. Use {{variables}} that reference environment-specific values.

Rotate Tokens in Scripts

For OAuth 2.0, use post-response scripts to capture and store new access tokens automatically.

Test Auth Failures

Create separate requests to test 401/403 responses with invalid credentials.

Document Required Scopes

Use the Docs tab to document which OAuth scopes or API key permissions are needed.

Next Steps

Scripts

Learn how to automate auth token refresh with scripts

Collection Settings

Configure collection-level authentication

Environment Variables

Manage auth credentials across environments

Tests

Write tests to validate authentication

Get Started

Core Concepts

Desktop App

CLI

Advanced

Integrations

​Authentication Modes

Basic Auth

Bearer Token

OAuth 2.0

API Key

AWS Sig v4

Digest Auth

NTLM Auth

WSSE Auth

​Setting Authentication Mode

​Basic Authentication

​Configuration

​Example in .bru File

​Using Script for Basic Auth

​Bearer Token

​Configuration

​Example

​OAuth 2.0

​Grant Types

​OAuth 2.0 Configuration Options

​OAuth 2.0 Example

​API Key Authentication

​Configuration

​Examples

​AWS Signature v4

​Configuration

​Example

​Digest Authentication

​Configuration

​Example

​NTLM Authentication

​Configuration

​Example

​WSSE Authentication

​Configuration

​Authentication Inheritance

​Inheritance Example

​Using Variables for Security

​Best Practices

​Next Steps

Scripts

Collection Settings

Environment Variables

Tests

Build docs developers (and LLMs) love

Authentication Modes

Setting Authentication Mode

Basic Authentication

Configuration

Example in .bru File

Using Script for Basic Auth

Bearer Token

Configuration

Example

OAuth 2.0

Grant Types

OAuth 2.0 Configuration Options

OAuth 2.0 Example

API Key Authentication

Configuration

Examples

AWS Signature v4

Configuration

Example

Digest Authentication

Configuration

Example

NTLM Authentication

Configuration

Example

WSSE Authentication

Configuration

Authentication Inheritance

Inheritance Example

Using Variables for Security

Best Practices

Next Steps