Ruby & Rails

Start integrating any APIs with the Bearer client for Ruby & Rails

Installing & initializing

gem install bearer-rails
gem install bearer-rails
Bearer::Configuration.setup do |config|
config.api_key = BEARER_SECRET_KEY

Replace the BEARER_SECRET_KEY with your Secret Key that can be found on the settings page of your Bearer account.

# in config/initializers/bearer.rb
Bearer::Configuration.setup do |config|
config.api_key = BEARER_SECRET_KEY
config.secret = BEARER_ENCRYPTION_KEY ## Used for the WebHook
# in config/routes.rb
Rails.application.routes.draw do
mount, at: '/bearer-webhooks'

Replace the BEARER_SECRET_KEY and the BEARER_ENCRYPTION_KEY with respectively your Secret Key and Encryption Key that can be found on the settings page of your Bearer account.

Calling APIs

Once you've added an API through the Bearer dashboard, you can make request to it as follow:

# GET request to the GitHub API
.get('/repositories', { query: { since: 364 } })

Most common HTTP methods are supported out-of-the-box, including .get() , .post(), .put()and.delete().

To pass parameters, construct your request as follow:

.get('/endpoint', {
query: { 'foo': 'bear'}, // your query parameters as key/value
body: {}, // your body as key/value or string
headers: { 'foo': 'bear' } // your headers as key/value

Credentials management

By default, all requests will be authenticated using the latest credentials saved into your account for that API. Thus, changing the API credentials in your account will be instantly reflected into your code.

If you want to use custom credentials, for example your customers credentials, first retrieve them on your frontend with the setup component, then update your code to use the .setup() method as follow:

# GET request to the GitHub API with custom credentials
# (retrieve a setupId with the Bearer setup component)
.get('/repositories', { query: { since: 364 } })

Dealing with OAuth APIs

When the API you want to use rely on OAuth as an authentication method, Bearer will handle the OAuth dance for you.

Just add a connect button to your frontend to let your users connect to the service. Then update your code to use the .auth() method as follow:

# POST request using an authId (only for OAuth APIs)
# (generate an authId with the Bearer connect button)
.post('/user/repos', { body: { name: 'Just setting up my' } })

Request timeout

The Ruby client timeout is set to 5 seconds per default. After that period of time, the HTTP connection will be closed by the client.

Bearer::Configuration.setup do |config|
# increase the request timeout to 10 seconds, and reduce the open connection timeout to 1 second
config.http_client_settings = { read_timeout: 10, open_timeout: 1 }
# it is also possible to set the read_timeout and other Net::HTTP client settings per integration
github = Bearer.integration("your integration id", { read_timeout: 10 })

You can increase the timeout up to 30 seconds only, which is the limit of our servers.

Tracking requests

The Bearer Ruby client allows you to set a correlationId to make logs grouping easier. This can be done by using the special Bearer-Correlation-Id header.

# Set the correlation id using `Bearer-Correlation-Id` header
github.get("/user/repos", headers: { "Bearer-Correlation-Id" => "your-correlation-id" })

On the Bearer dashboard, you can then filter the logs using your-correlation-id.

Receiving Webhooks

# in app/webhooks/my_handler.rb
class MyHandler
include BearerRails::Webhook
integration_handler "github"
def call

Client reference

This page contains the most common use case for the Bearer API client in Ruby & Rails. If you are trying to achieve something not listed here, have a look at the full client reference on the respective repository on GitHub:

  • Ruby client full reference;

  • Rails client full reference.

Each client reference includes details about the functions, classes, return types, arguments and more, supported by tutorials and examples. As well as the source code of the client.