Authentication Methods

This document is intended if you want to add a custom API to Bearer.

If you are using an API from the API Hub, the informations below are not needed.

Bearer support out-of-the-box most API authentication methods:

For every custom API you want to use Bearer with, the only thing you have to do is provide some basic information about the API authentication method and associated request. In return, our API clients will abstract all the code & logic for you.

You will be asked to provide those as JSON config files directly on the dashboard, as shown below:

OAuth 2

Authentication Configuration

When adding an OAuth 2 based API, this is the default authentication config structure:

{
"authorizationURL": "https://example.com/authorizationUrl",
"tokenURL": "https://example.com/tokenUrl",
"authType": "OAUTH2",
"tokenParams": {},
"authorizationParams": {},
"config": {
"scope": []
}
}

You will have to fill some mandatory OAuth parameters specific to the API Provider:

  • authorizationURL

  • tokenURL

  • scope

You will usually find this on the API provider developer page. Here is an example for the Github API.

Since there is no such thing as standard OAuth implementation, 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:

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

If you need to pass additional parameters to the token URL you can use the tokenParamsattribute:

"tokenParams": {
"param": "value"
}

Some API providers use separate URLs for the initial token exchange and for refreshing tokens. To specify a URL for refreshing tokens that is different to the token URL you can use the refreshURL attribute:

"refreshURL": "https://example.com/refreshUrl"

Request Configuration

The request config also has to be configured properly:

{
"headers": {
"Accept": "application/json",
"User-Agent": "Bearer.sh",
"Authorization": "Bearer ${auth.accessToken}"
},
"baseURL": "https://api.example.com/",
"params": {}
}

Most of the time the only thing you need to do is to replace the baseURL value by the API provider base URL.

Basic Auth

Authentication Configuration

For APIs relying on Basic authentication, you don't need to change anything on the authentication config:

{
"authType": "BASIC"
}

Request Configuration

The request config has to be configured properly:

{
"headers": {
"Accept": "application/json",
"User-Agent": "Bearer.sh",
"Authorization": "Basic ${auth.basic}"
},
"baseURL": "https://api.example.com/",
"params": {}
}

You have to replace the baseURL value by the API provider base URL. Most of the time that's the only thing you'll have to do for APIs using a Basic authentication.

API Key

Authentication Configuration

For APIs relying on API Key authentication, the authentication config is straightforward:

{
"authType": "APIKEY"
}

Request Configuration

The request config has to be configured properly:

{
"headers": {
"Accept": "application/json",
"User-Agent": "Bearer.sh",
"Authorization": "Bearer ${auth.apiKey}"
},
"baseURL": "https://api.example.com/",
"params": {}
}

You will have to replace the baseURL value by the API provider base URL. You should also double check where to pass the API key using ${auth.apiKey}.It is sometimes in the headers (as shown above); sometimes as a parameter.

The API reference will explain that in the Authentication part. If you can't find it, contact us and we will ask the API provider for you.

NoAuth

Some API may not require any authentication mechanism. In this case, simply use this option and voilà!