Header injection support on BrowserStack Automate

Pass HTTP headers as capabilities in your test sessions with BrowserStack Automate.

Use HTTP headers to pass additional context to your test session. BrowserStack supports both default HTTP headers along with custom headers that your organization might use.

In this guide, you will learn how to:

• Pass HTTP headers using headerParams
• Pass HTTP headers using customHeaderParams
• Possible usage scenarios

Pass HTTP headers using headerParams

Use the headerParams capability for W3C protocol and browserstack.headerParams capability for JSON wire protocol in your test scripts to pass context. This capability accepts a JSON string with up to 5 key-value pairs as HTTP headers.

MutableCapabilities capabilities = new MutableCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("headerParams", "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}");
capabilities.setCapability("bstack:options", browserstackOptions);

var capabilities = {
    'bstack:options' : {
        "headerParams" : "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}"  
    },
}

Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("headerParams", "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}");
capabilities.AddAdditionalOption("bstack:options", browserstackOptions);

desired_cap = {
'bstack:options' : {
    "headerParams" : "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}"  
    }
}

capabilities = {
    'bstack:options' => {
        "headerParams" => "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}"
    }
}

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("browserstack.headerParams", "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}");

var capabilities = {
    "browserstack.headerParams" : "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}" 
}

capability.AddAdditionalCapability("browserstack.headerParams", "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}");

desired_cap = {
    "browserstack.headerParams" : "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}" 
}

caps = Selenium::WebDriver::Remote::Capabilities.new
caps["browserstack.headerParams"] = "{\"header_param_key1\":\"header_param_value1\", \"header_param_key2\":\"header_param_value2\"}" 

The following image shows an HTTP header, Authorization, passed as part of the HTTP request in a test session.

Pass HTTP headers using customHeaderParams

Use the customHeaderParams capability for W3C protocol and browserstack.customHeaderParams capability for JSON wire protocol in your test scripts to pass headers that apply to specific domains. This capability accepts a JSON string containing an array of rules, where each rule specifies headers and optional domain-matching criteria.

MutableCapabilities capabilities = new MutableCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("networkLogs", true);
browserstackOptions.put("customHeaderParams", "[{\"headers\": {\"X-Auth\": \"abc\"}, \"includeDomains\": [\"example.com\"]}, {\"headers\": {\"X-Trace\": \"1\"}, \"excludeDomains\": [\"cdn.example.com\"]}, {\"headers\": {\"X-Global\": \"1\"}}]");
capabilities.setCapability("bstack:options", browserstackOptions);

const capabilities = {
  'bstack:options': {
    networkLogs: true,
    customHeaderParams: JSON.stringify([
      { headers: { 'X-Auth': 'abc' }, includeDomains: ['example.com'] },
      { headers: { 'X-Trace': '1' }, excludeDomains: ['cdn.example.com'] },
      { headers: { 'X-Global': '1' } }
    ])
  }
};

using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

ChromeOptions capabilities = new ChromeOptions();
Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("networkLogs", true);
browserstackOptions.Add("customHeaderParams", "[{\"headers\": {\"X-Auth\": \"abc\"}, \"includeDomains\": [\"example.com\"]}, {\"headers\": {\"X-Trace\": \"1\"}, \"excludeDomains\": [\"cdn.example.com\"]}, {\"headers\": {\"X-Global\": \"1\"}}]");
capabilities.AddAdditionalOption("bstack:options", browserstackOptions);

import json

options = {
    'networkLogs': True,
    'customHeaderParams': json.dumps([
        {'headers': {'X-Auth': 'abc'}, 'includeDomains': ['example.com']},
        {'headers': {'X-Trace': '1'}, 'excludeDomains': ['cdn.example.com']},
        {'headers': {'X-Global': '1'}}
    ])
}

capabilities = {
    'bstack:options': options
}

require 'json'

capabilities = {
  'bstack:options': {
    networkLogs: true,
    customHeaderParams: JSON.generate([
      { headers: { 'X-Auth': 'abc' }, includeDomains: ['example.com'] },
      { headers: { 'X-Trace': '1' }, excludeDomains: ['cdn.example.com'] },
      { headers: { 'X-Global': '1' } }
    ])
  }
}

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("browserstack.networkLogs", true);
capabilities.setCapability("browserstack.customHeaderParams", "[{\"headers\": {\"X-Auth\": \"abc\"}, \"includeDomains\": [\"example.com\"]}, {\"headers\": {\"X-Trace\": \"1\"}, \"excludeDomains\": [\"cdn.example.com\"]}, {\"headers\": {\"X-Global\": \"1\"}}]");

const capabilities = {
  'browserstack.networkLogs': true,
  'browserstack.customHeaderParams': JSON.stringify([
    { headers: { 'X-Auth': 'abc' }, includeDomains: ['example.com'] },
    { headers: { 'X-Trace': '1' }, excludeDomains: ['cdn.example.com'] },
    { headers: { 'X-Global': '1' } }
  ])
};

using OpenQA.Selenium;
using OpenQA.Selenium.Chrome;

DesiredCapabilities capabilities = DesiredCapabilities.Chrome();
capabilities.SetCapability("browserstack.networkLogs", true);
capabilities.SetCapability("browserstack.customHeaderParams", "[{\"headers\": {\"X-Auth\": \"abc\"}, \"includeDomains\": [\"example.com\"]}, {\"headers\": {\"X-Trace\": \"1\"}, \"excludeDomains\": [\"cdn.example.com\"]}, {\"headers\": {\"X-Global\": \"1\"}}]");

from selenium.webdriver.common.desired_capabilities import DesiredCapabilities
import json

capabilities = DesiredCapabilities.CHROME
capabilities['browserstack.networkLogs'] = True
capabilities['browserstack.customHeaderParams'] = json.dumps([
    {'headers': {'X-Auth': 'abc'}, 'includeDomains': ['example.com']},
    {'headers': {'X-Trace': '1'}, 'excludeDomains': ['cdn.example.com']},
    {'headers': {'X-Global': '1'}}
])

require 'json'

capabilities = Selenium::WebDriver::Remote::Capabilities.chrome
capabilities['browserstack.networkLogs'] = true
capabilities['browserstack.customHeaderParams'] = JSON.generate([
  { headers: { 'X-Auth': 'abc' }, includeDomains: ['example.com'] },
  { headers: { 'X-Trace': '1' }, excludeDomains: ['cdn.example.com'] },
  { headers: { 'X-Global': '1' } }
])

Domain-matching semantics

When you specify domain rules for customHeaderParams, BrowserStack matches each rule against the request hostname, lowercased and with the port removed:

• Plain string: matches the exact domain and its subdomains. For example, example.com matches example.com, www.example.com, and a.b.example.com.
• Regex pattern: matches domains against a regex written as /pattern/flags. Only the i (case-insensitive) and m (multiline) flags are supported. All other flags are ignored.
• No includeDomains: if a rule omits includeDomains, its headers apply to all domains.
• excludeDomains precedence: when a rule specifies both includeDomains and excludeDomains, excludeDomains takes precedence.

Possible usage scenarios

You can use Default HTTP headers with custom headers for situations like:

• Support for third-party integration that requires passing authentication details to allow access to restricted sites.
• Pass additional context to identify different requests when using mocking servers.
• Pass custom headers, such as your BrowserStack Access Key, to applications, such as AWS Web Application Firewall to identify where a request originates from.