Setup component

Frequently asked questions about Bearer setup component.

What is the purpose of the setup component?

Bearer provides API credentials management, to bring more security around these critical strings.

Entering an API key on the dashboard

For most developers using Bearer, managing credentials is totally transparent. Indeed, all requests performed with your Bearer's Secret Key use the latest credentials saved on the dashboard for that API. This cleans up your codebase and prevents credentials-leak.

However, in some cases, you might want to programatically save credentials, especially if you start to store credentials of third-parties, like if you are building a marketplace of integrations and need to make requests to APIs using the credentials of your own customers.

How the setup-component works?

For each API added to your Bearer account, an endpoint /bearer-setup-save is available to save new credentials for that API.

Requests to that endpoint expect a format detailed below, which is the only validation performed. In particular, there's no validation on the format of the string and/or if it corresponds to a certain pattern. On success, Bearer always responds with a setupId which is a reference to the credentials saved.

Here's an example to save credentials for Stripe API using the API client for JavaScript:

const bearerClient = bearer('YOUR-PUBLISHABLE-KEY')
bearerClient
.integration('stripe')
.invoke('bearer-setup-save', { setup: { type: 'APIKEY', apiKey: 'stripe-api-key' }})
.then(({ data }) => console.log(data.setupId))

The payload of the request to save credentials varies depending on the authentication methods of the API (see below).

What types of credentials can I store?

The following types of credentials can be stored securely:

Type

Description

Request payload (JSON)

API Key

a single string

{ "type": "APIKEY", "apiKey": "..." }

Basic

a pair of a username / password

{ "type": "BASIC", "username": "...", "password": "..." }

OAuth2

a pair of client ID / client secret

{ "type": "OAUTH2", "clientId": "...", "clientSecret": "..." }

OAuth1

a pair of consumer key / consumer secret

{ "type": "OAUTH1", "consumerKey": "...", "consumerSecret": "..." }

Requests shall stricly comply with the payload format to success. Otherwise an error will be thrown.

How to use the setupId?

All our APIs clients provides a setup() function to let you pass a setupId. Here are some examples to adapt:

Node.js
Python
Ruby
PHP
JavaScript
// GET request to the Stripe API with custom credentials
bearer.integration("stripe")
.setup("REPLACE-WITH-A-SETUP-ID")
.get("/charges")
.then(({ data }) => { console.log(data) });

Learn more about our API client for Node.js.

# GET request to the Stripe API with custom credentials
bearer.integration("stripe") \
.setup("REPLACE-WITH-A-SETUP-ID") \
.get("/charges")

Learn more about our API client for Python.

# GET request to the Stripe API with custom credentials
bearer.integration('stripe')
.setup('REPLACE-WITH-A-SETUP-ID')
.get('/charges')

Learn more about our API client for Ruby.

# GET request to the Stripe API using custom credentials
$bearer
->integration('stripe')
->setup('REPLACE-WITH-A-SETUP-ID')
->get('/charges');

Learn more about our API client for PHP.

// GET request to the Stripe API with custom credentials
bearerClient.integration("stripe")
.setup("REPLACE-WITH-A-SETUP-ID")
.get("/charges")

Learn more about our API client for JavaScript.

Is there a limit on the number of API credentials stored?

No. You can store as much credentials per API as you want. There might be others limits applicable though, like the number of APIs that you can add on your account.

How to delete credentials?

At the moment, you can't delete credentials.

Can I retrieve credentials once saved?

Bearer's vault works one-way only. Once you have stored credentials, there's no method to retrieve them.