Add the Bearer Agent

Getting Started

Installing the Bearer Agent generally only takes a few minutes. You will need an account on Bearer.sh to obtain your secret key.

To enable the Bearer Agent within your application, you'll need to:

  1. Install the Agent and initialize it in your application.

  2. Set up any optional configuration settings.

To get started, select your platform:

Node.js
Ruby
Node.js

Open a terminal and install the @bearer/node-agent module into your project:

npm install --save @bearer/node-agent
# OR
yarn add @bearer/node-agent

Now, open your application main script (e.g., index.js or main.js) and initialize the Bearer agent at the top:

const Bearer = require('@bearer/node-agent')
Bearer.init({ secretKey: 'YOUR_BEARER_SECRET_KEY' })

Your Bearer Secret Key, secretKey, can be found in the settings for your app on the Bearer Dashboard at Settings > Keys.

We strongly recommend initializing the Bearer agent as early as possible in your codebase. This ensure that all external HTTP requests performed on your application are monitored.

Now, you can start your application (e.g., node index.js). All API calls will be monitored and available on your Bearer dashboard.

Ruby

Add bearer-agent to your Gemfile:

gem 'bearer-agent'

Next, run bundle to install the latest version of bearer-agent.

bundle

Alternately, you can install it yourself:

gem install bearer-agent

Next, initialize the Bearer Agent with your Secret Key:

require 'bearer-agent'
Bearer.init_config do |config|
config.secret_key = "YOUR_BEARER_SECRET_KEY" # Required, string: Your Bearer Secret Key
end

Your Bearer Secret Key, config.secret_key, can be found in the settings for your app on the Bearer Dashboard at Settings > Keys.

Now, you can start your application. All API calls will be monitored and available on your Bearer dashboard.

Keep your data protected

To keep your application safe and prevent sensitive data leaks, we recommend that you sanitize your data before sending it to Bearer. The best way to do it is to use the Agent's configuration options:

Node.js
Ruby
Node.js

Add sanitization settings to your Bearer initialization. The default sanitization values are set as follows:

Bearer.init({
"stripSensitiveData": true,
"stripSensitiveKeys": ["^authorization$", "^client.id$", "^access.token$", "^client.secret$"],
"stripSensitiveRegex": "[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*"
})

This default configuration prevents most of your API credentials from being sent to Bearer.

Sanitization options explained

  • stripSensitiveData - Globally enable/disable data sanitization. It's enabled by default. If you set it to false no sanitization will take place, and all the data will be sent to Bearer unfiltered.

  • stripsSensitiveKeys - List of key names regex patterns that will be applied to sanitize values in headers, query parameters, or the response body. If you specify "stripSensitiveKeys": "^authorization$" the following sanitization actions would take place:

    • In headers: the value of the "authorization" header will be sanitized and be sent to Bearer as authorization: [FILTERED]

    • In query string parameters: the value of the "authorization" query parameter will be sanitized. In the Bearer dashboard your URL will look like: http://www.example.com/endpoint?authorization=[FILTERED]

    • In the response body: any value of "authorization" key in response payload will be replaced with [FILTERED] (e.g., { "name": "John", "authorization": "granted" } will be sent to the Bearer dashboard as { "name": "John", "authorization": "[FILTERED]" }. This rule only applies to responses with a Content-Type header set to application/json.

  • stripSensitiveRegex - A regular expression that will be used to sanitize any value in headers, query string parameters, or the response body. Bearer will check all the values sent in the request or response and will replace matching patterns with [FILTERED].

Ruby

Use the initializer file to set up the sanitization level that best suits your needs:

The default sanitization values are set as follows:

Bearer.init_config do |config|
config.strip_sensitive_data = true
config.strip_sensitive_keys = [/^authorization$/i, /^client.id$/i, /^access.token$/i, /^client.secret$/i]
config.strip_sensitive_regex = %r{[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\.[a-zA-Z0-9-]+)*}
end

This default configuration prevents most of your API credentials from being sent to Bearer.

Sanitization options explained

  • config.strip_sensitive_data - Globally enable/disable data sanitization. It's enabled by default. If you set it to false no sanitization will take place, and all the data will be sent to the Bearer dashboard as-is.

  • config.strips_sensitive_keys - List of key names regex patterns that will be applied to sanitize values in headers, query parameters or response body. If you specify config.strip_sensitive_keys = [/authorization/] the following sanitization actions would take place:

    • In headers: "authorization" header value will be sanitized and would be sent to the Bearer dashboard as "authorization: [FILTERED]"

    • In query string parameters: "authorization" query parameter value will be sanitized, and in the Bearer dashboard your URL will look like: http://www.example.com/auth?authorizaiton=[FILTERED]

    • In application/json response body: Any value of "authorization" key in response payload will be replaced with "[FILTERED]" (e.g., { "name": "John", "authorization": "granted" } will be sent to the Bearer dashboard as { "name": "John", "authorization": "[FILTERED]" }

  • config.strips_sensitive_regex - A regular expression that will be used to sanitize any value in headers, query string parameters or response body. Bearer will check all the values sent in the request or response and will replace matching patterns with "[FILTERED]".

For a full list of supported configuration settings, as well as details on other methods of configuration, check out the Configuration Reference.

With the Agent set up and monitoring your APIs, use the Dashboard to better manage your API usage.