Adding a custom API

This guide will show you how to add a custom API to your Bearer account.

Adding a custom API is a 3-steps process:

This guide is about adding a custom API. Before following this guide, make sure the API you want to add is not listed in our API Hub. If it is, you will save precious time.

Configure the custom API

First, open the Add a new API page of the Dashboard:

Add a new (custom) API to your Bearer account

On that page, you will be prompt with a form that ask for the API configuration. It's basically the identity card of an API. To ease the process, we have splitted it in three parts:

General information

Provide the API name and select its authentication type. It should be one of the following type: "API Key" | "Basic" | "OAuth1" | "OAuth2" | "NONE".

If you don't know the authentication type yet, have a look at the API reference website. There is generally an "Authentication" section where the API provider explains that.

Request configuration

A request configuration tells Bearer how to perform each requests to the API. It includes:

Request base URL

It consists of the HTTP base URL to send request to. The API provider will give it on their API reference website. It's generally something likehttps://api.example.com/v1/.

Request headers

Provide here all the HTTP headers that you want to send alongside every single request sent to the API. You will still be able to send more headers on a per request basis, using one of our clients. We recommend you to make sure that the headers added are safe to use on each endpoints of the API.

Based on the authentication type of the API, that part is prefilled with how most-common API works. But there are no standard way of proceeding. So you should pay extra-attention here to the Authorization header which might be different from one API to the other.

{
"Accept": "application/json",
"User-Agent": "Bearer.sh",
"Authorization": "Bearer ${auth.apiKey}"
}

Some headers can be replaced automatically, for instance everything related to the credentials. Learn more about that below.

Request parameters

Provide here all the query string to send alongside every single request sent to the API. You will still be able to send more parameters on a per request basis, using one of our clients. So make sure that the parameters is global and safe to use on each endpoints of the API.

Generally, that field is used for exotic APIs that ask to provide credentials in the request parameters.

{
"queryParams1": "foo",
"queryParams2": "bar"
}

For instance, with the previous configuration, each request will contain the following query parameters:?queryParams1=foo&queryParams2=bar

Request variables

Each part of the request (the baseURL, the headers and the parameters) can be customized to use variables, right from the configuration. This let you make authenticated request, using "Authorization": "${auth.apiKey}". As well much more powerful query.

Here's a list of the available variables depending on the API authentication types:

API Key
Basic
OAuth2
OAuth1

Variable

Description

${auth.apiKey}

The API Key provided

(*) If you pass a setup-id alongside your request, the variable will be replaced with the relevant credentials associated with that ID. Otherwise, it will use the credentials provided through the dashboard.

Variable

Description

${auth.basic}

The BASIC token credentials. It's a base64 of the username and password.

${auth.username}

The username saved by Bearer (*)

${auth.password}

The password saved by Bearer (*)

(*) If you pass a setup-id alongside your request, the variable will be replaced with the relevant credentials associated with that ID. Otherwise, it will use the credentials provided through the dashboard.

Variable

Description

${auth.accessToken}

The accessToken stored by Bearer on success of an OAuth2 dance.

Variable

Description

${auth.consumerKey}

The consumer key saved (*)

${auth.consumerSecret}

The consumer secret saved (*)

${auth.oauth1}

The OAuth1 signature of the request, based on the OAuth dance.

${auth.tokenSecret}

The token secret generated by the OAuth dance

${auth.signatureMethod}

The signature method provided from the configuration

(*) If you pass a setup-id alongside your request, the variable will be replaced with the relevant credentials associated with that ID. Otherwise, it will use the credentials provided through the dashboard.

Aside from the authentication-related variables, Bearer lets you create custom variables, based on the headers provided.

Global Variable

Description

${headers.*}

Where * is any of the headers passed by the client (e.g. X-Foo-Bar)

This is pretty useful for some APIs that use a different baseURL depending on the account. For instance the Salesforce API uses a configuration like the following variable in the baseURL:

https://${headers.salesforce_instance}.salesforce.com/services

Authentication configuration

This part is only required for OAuth based APIs. It will not popup for any other type of API.

The OAuth authorization methods includes several back-and-forth between the API provider and the application. Bearer handles the whole OAuth flow, including OAuth1 and OAuth2, with a simple HTML/JS connect button.

And we did our best to make it as simple as possible to translate that HTTP flow into an HTML form. All fields of the form are required and you will find the right values within the API documentation.

Keep in mind that labels on Bearer.sh are named after the relevant OAuth standard, but some APIs might use different names. It's a source of confusion, so feel free to get in touch with us and we will be happy to help you on that part.

Retrieve your API credentials

Now that your API is configured, you need to tell Bearer what are your API credentials. So Bearer will be able to perform authenticated request on your behalf.

If the API doesn't require authentication, which is not so common, you can skip that step.

Credentials differ whether the API uses OAuth2, OAuth1, API Key or Basic as an authentication schema. Here are a few examples:

API Key
OAuth2
OAuth1
Basic

An API Key is a secret string shared between a developer and an API provider. Here are some (not working) examples of API keys:

AIRTABLE_APIKEY=key1ROqjCKzSzv4x0
CRUNCHBASE_APIKEY=83dedad0728baaef3ad3f50bd05ed030
STRIPE_APIKEY=sk_live_0c5c90ffb7b04fa89b6a05413f6d0419

APIs using an API Key include: Clearbit, Front, Google Maps, Telegram, etc.

OAuth2 credentials consist of a pair of client_id and client_secret. Here are some (not working) examples of OAuth2 credentials:

GITHUB_CLIENT_ID=83dedad0728baaef3ad3f50bd05ed030
GITHUB_CLIENT_SECRET=60919e5d63d0dccc815973f81379cb8a
SLACK_CLIENT_ID=030de50db05f3da3feaab8270daded38
SLACK_CLIENT_SECRET=a8bc97318f379518cccd0d36d5e91906

APIs using OAuth2 include: GitHub, LinkedIn, Typeform, Google Sheets, etc.

OAuth 1.0 and 1.0a credentials consist of a pair of consumer_key and consumer_secret. Here are some (not working) examples of OAuth1 credentials:

TWITTER_CONSUMER_KEY=030de50db05f3da3feaab8270daded38
TWITTER_CONSUMER_SECRET=a8bc97318f379518cccd0d36d5e91906
XERO_CONSUMER_KEY=83dedad0728baaef3ad3f50bd05ed030
XERO_CONSUMER_SECRET=60919e5d63d0dccc815973f81379cb8a

APIs using OAuth1 include Trello, Twitter, Xero, etc.

Basic authentication consists of a pair of username and password. Here are some (not working) examples of Basic credentials:

MAILJET_USERNAME=030de50db05f3da3feaab8270daded38
MAILJET_PASSWORD=a8bc97318f379518cccd0d36d5e91906
ZENDESK_USERNAME=demo@bearer.sh
ZENDESK_PASSWORD=83dedad0728baaef3ad3f50bd05ed030

APIs reyling on Basic authentication include: Twilio, Zendesk, Mailchimp, etc.

You will generally find your API credentials from the API developer website, on your account settings page. In case you can't find them, feel free to reach us.

Once you have retrieved your credentials, provide them on the Instructions page:

Saving credentials for a custom API

Try it out!

You are close to the end 🙌 Let's just confirm that everything is all set by performing a simple API call. We recommend using cURL for that as it's quite handy, but you can definitely try with one of our API clients.

If your custom API uses OAuth2 or OAuth1, giving it a try requires an extra step. You shall use the "Connect" button which triggers an OAuth authentication flow.

  1. On the Instructions page, select the cURL tab, then click "Copy".

  2. Edit the cURL command to change /endpoint with a working endpoint of the API. For testing purpose, we recommend trying to retrieve something like your account information. Look at the API reference to test one of the endpoints.

cURL command to call a custom API

Well done! 🥳

Now that you have setup this custom API, you can start using it like any other APIs from our API Hub.

If you are feeling generous, we encourage you to spread how to configure that custom API to the Bearer community in our shared Slack. You might help tons of others developers!

FAQ

How many custom APIs can I have?

You can add as much custom APIs as you want.

What differs a custom APIs to one from the API Hub?

All APIs listed in our API Hub have been pre-configured to be easily added into your Bearer account. So you don't spend time on configuration and can focus on the data.

But once you have added a custom API, you have access to all Bearer features for that new API (full logging, monitoring, credentials management, etc.).

Troubleshooting

If your test request returned an error, first look at the logs in the Logs page. You will find useful information to help you debugging the issue. For notice, most common errors are:

  • the API credentials aren't the right ones;

  • the request configuration is malformed;

  • the authentication configuration is wrong (especially for OAuth APIs).

Any change made to the API configuration is applied in real time.

If you just can't make it, feel free to reach us in the #troubleshooting channel of the Bearer community. We're here to help! - Not part of our Slack? Click here to join it.