Bearer

The Bearer Documentation Hub

Welcome to the Bearer documentation hub. You'll find comprehensive guides and documentation to help you start working with Bearer as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Changelog

API Authentication

When creating a new Scenario, the CLI will ask what kind of authentication the queried API require, Bearer currently support four options:

  • OAuth2
  • Basic Auth
  • API Key
  • NoAuth

OAuth2

Most modern web application provide OAuth2, letting end-users authenticate with their account and in return provide the developer with an Access Token bearing some specific authorization depending of scopes.

When creating an OAuth2 Scenario, the CLI generate a pre-configured auth.config.json file. You have to provide some OAuth parameters regarding the API provider:

  • authorizationURL
  • tokenURL
  • scope

Also two optionals one:

  • tokenParams
  • authorizationParams

Usually you will find those information on the API provider developer page, here is an example with the Github API.

Callback URL

the API provider will always ask for a callback URL, you can use https://int.bearer.sh/v1/auth/callback or the placeholder {{CALLBACK_URL}}

When creating an OAuth Application, the provider will issue credentials (Client ID and Client Secret). Those credentials have to be stored securely and never be revealed.

Bearer automatically generate a group of Setup Root Components used to retrieve and store those credentials. You will be able to use your own credentials or ask you users their own (usually some kinds of admin user), this choice is up to you.

Learn more about OAuth 2.0:

Advanced Configuration

By default the generated auth.config.json provides a generic OAuth 2 configuration, but since there is no such thing as standard OAuth 2 you might need to tweak it.

The attribute authorizationParams is used to add additional parameters sent to the authorization URL, for example LinkedIn implementation ask you to pass the redirect_uri here:

"authorizationParams": {
   "redirect_uri": "https://int.bearer.sh/v1/auth/callback"
 }

If you need to pass additional parameters to the token URL you can use the tokenParams attribute.

"tokenParams": {
   "redirect_uri": "https://int.bearer.sh/v1/auth/callback"
 }

Local Development

In local development Bearer won't perform the OAuth flow, instead you have to manually generate an Access Token.

To generate an Access Token we encourage you to use Postman.
Open Postman, click on the Authorization tab, select "OAuth 2.0" in Type and then click on *Get New Access Token" as show below:

Then fill-in your OAuth App info (notice the callback URL), below an example with Github API:

Postman will return your Access Token:

Finally use this generated Access Token in config.dev.js:

module.exports = {
  global: { authAccess: { accessToken: '7e5c2696d79XXXXXXXXXX' } }
}

Now you should be able to perform API call in development 🎉
In production credentials will be retrieved from the Setup Components.

More about OAuth2

If you want to understand how OAuth2 works in detail we suggest you to read this article that Digital Ocean wrote few years ago.

Basic Auth

When creating a Basic Auth Scenario, the CLI generate a working pre-configured auth.config.json file:

{
  "authType": "BASIC",
  "setupScreens": [
    {
      "type": "text",
      "label": "Username",
      "controlName": "username"
    },
    {
      "type": "password",
      "label": "Password",
      "controlName": "password"
    }
  ]
}

Bearer automatically generate a group of Setup Root Components used to retrieve and store the Basic Auth credentials. You will be able to use your own credentials or ask users their own (**usually some kinds of admin user), this choice is up to you.

In local development, you can use a test username & password by changing the authAccess field in the config.dev.js file:

module.exports = {
  global: { authAccess: { username: "Foo", password: "Bar" } },
}

In production credentials will be retrieved from the Setup Components.

API Key

When creating an API Scenario, the CLI generate a working pre-configured auth.config.json file:

{
  "authType": "APIKEY",
  "setupScreens": [
    {
      "type": "password",
      "label": "Api Key",
      "controlName": "apiKey"
    }
  ]
}

Bearer automatically generate a group of Setup Root Components used to retrieve and store the API Key. You will be able to use your own Key or ask users their own (**usually some kinds of admin user), this choice is up to you.

In local development, you can use a test API Key by changing the authAccess field in the config.dev.js file:

module.exports = {
  global: { authAccess: { apiKey: 'CHANGE_ME' } },
}

In production credentials will be retrieved from the Setup Components.

Authorization Headers

You can see that in the client.tsfile that the API Key is sent as an Authorization header. Feel free to change the behavior in this file if needed, yo will see some other options commented (ex: Basic auth).

NoAuth

Some API may not require any authentication mechanism, in this case you use this option when generating a new Scenario.