Connect button

Frequently asked questions about the Bearer connect button.

What is the connect button?

The connect button is an HTML/JS <button> that triggers an authentication flow when clicked.

Screenshot of a connect button

By adding this button into your frontend, an OAuth dance is triggered every time a user clicks on it. Thus, on success, your application is granted a personal and limited access to a user account.

What is the purpose of the connect button?

Some APIs let you perform requests on behalf of a user. For example, the Gmail API lets you retrieve emails of a user. To enable this kind of personal and limited access to users data, APIs providers use an open authentication framework (the OAuth framework).

Using the Bearer connect button, you can quickly and easily be granted access to all these APIs.

How to add a connect button into my application?

Adding a connect button is a 2 steps process, one step on the API developer website, another step on the Bearer dashboard:

On the API developer website (e.g. Gmail API):

  1. Sign in to the API developer website (e.g. Gmail API)

  2. Create an application (if you don't already have one already)

  3. On the settings page of this application:

    1. make sure you have registered the following callback URL:https://int.bearer.sh/v2/auth/callback

    2. Retrieve your API credentials

Now, open the Bearer dashboard:

  1. Select the API on which you want to add a connect button

  2. Open the instructions page of that API and fill out the credentials tab (if not already provided)

  3. On the bottom of the page, click on Ask your user's identity and follow the instructions:

Ask your user's identity on the instructions

Do I need to create an application on the API?

Yes. The connect button helps your quickly trigger OAuth dance, using your own application. Thus, you need to first register an application on the API developer website. Sometimes, API provider call it "App" or "Project".

What is the callback URL to use?

To perform OAuth connection, the API provider will ask you for an authorization callback URL. Register the following URL on the API developer website:

https://int.bearer.sh/v2/auth/callback

Does Bearer support both OAuth1 and OAuth2 framework?

Yes. The connect button will automatically perform an OAuth1 or OAuth2 dance, based on the authentication method used by the distant API.

What is an authId?

It's a universally unique identifier (UUID) automatically generated by Bearer when a user has successfully completed the connect process. It has 36 characters and looks something like this 123e4567-e89b-12d3-a456-426655440000.

Behind this string, Bearer stores all the information of the OAuth dance, including the access_token and the refresh_token. Every time you request contains an authId we retrieve the relevant information and send them to the API to authenticate the request.

Can I pass my own authId?

Yes, you can pass your own like this:

bearerClient.connect('api-name', {
authId: 'a-secure-non-guessable-auth-id'
})

Just make sure it's unguessable enough to improve your security.

Does Bearer handle refreshing token?

Yes. For each request performed to OAuth APIs, when Bearer detects an error related to an expired access_token, we will automatically refresh the token and retry the request.

So your app doesn't event notice it. It happens automatically and is recorded in your logs every time we have performed such refresh request.