API Authentication

When creating a new integration, the CLI will start by asking the authentication mechanism of the API Provider you wish to query. Bearer currently supports five authentication methods out-of-the-box:

OAuth 1

Currently, Bearer only supports OAuth 1.0 Revision A implementation at the moment.

Configuration

When creating an OAuth 1 based integration, the framework generates an authentication configuration file:

auth.config.js
{
"requestTokenURL": "https://example.com/oauth/RequestToken",
"accessTokenURL": "https://example.com/oauth/AccessToken",
"userAuthorizationURL": "https://example.com/oauth/Authorize",
"callbackURL": "https://int.bearer.sh/v2/auth/callback",
"authType": "OAUTH1",
"signatureMethod": "HMAC-SHA1",
"tokenParams": {},
"authorizationParams": {},
"config": {
"scope": []
}
}

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

  • requestTokenUrl

  • accessTokenUrl

  • userAuthorizationUrl

  • scope

Optionally, you can also use:

  • tokenParams

  • authorizationParams

You will usually find this information on the API provider's developer page.

Callback URL

When working with OAuth, the API provider requires you to register on their developer portal and create an OAuth App. When creating an OAuth App, you will need to provide Bearer's Callback URL:

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

In return, the API Provider will give you a set of OAuth credentials, Client ID and Client Secret.

API Client

An API client is also configured by default:

functions/client.ts
import axios from 'axios'
export default function(token: string) {
const headers = {
'Accept': 'application/json',
'User-Agent': 'Bearer',
'Authorization': `token ${token}`
}
return axios.create({
baseURL: 'https://api.example.com',
timeout: 5000,
headers
})
}

You will have to replace the baseURL value by the API provider base URL.

The function takes a token parameter which corresponds to the user's access token that Bearer retrieves and stores and store for you as part of the OAuth flow.

Local Development

To simplify working with the API, OAuth integrations rely on a static access token when used in the local development environment.

Once the authentication is configured (cf previously), you can generate an access token from the CLI:

NPM
Yarn
npm run bearer setup:auth
yarn bearer setup:auth

Next, you will be prompted to provide your OAuth credentials:

? Client ID: [hidden]
? Client secret: [hidden]

ItThis should open up your browser, trigger the OAuth dance and return a static access token:

This will forward it to the CLI and stores it in the local.config.jsoncfile:

$ cat local.config.jsonc
{
"setup": {
"auth": {
"accessToken": "a0facb69f0a047c9b9475xxxxxxxxxxxxxx"
}
}
}%

This access token is automatically used by the event.context.auth.accessToken object in development, so you can easily build and test functions:

Client(event.context.auth.accessToken).get('/an-endpoint')

Once the integration is deployed, you will provide your OAuth credentials in the Settings tab of the integration and the OAuth dance will be triggered by embedding a Connect Component (learn more).

Alternatively, you can ask your users to provide their own OAuth credentials by embedding a Setup Component (learn more).

OAuth 2

Configuration

Many modern APIs provide OAuth 2 support, letting end-users authenticate with their account and in return providing developers with an access token bearing some specific authorization, depending of scopes.

When creating an OAuth 2 based integration, the framework generates an authentication configuration file:

auth.config.json
{
"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.

Callback URL

When working with OAuth, the API provider requires you to register on their developer portal and create an OAuth App. When creating an OAuth App, you will need to provide Bearer's Callback URL:

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

In return, the API Provider will give you a set of OAuth credentials, Client ID and Client Secret.

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, 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:

auth.config.json
"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:

auth.config.json
"tokenParams": {
"param": "value"
}

API Client

An API client is also configured by default:

functions/client.ts
import axios from 'axios'
export default function(token: string) {
const headers = {
'Accept': 'application/json',
'User-Agent': 'Bearer',
'Authorization': `token ${token}`
}
return axios.create({
baseURL: 'https://api.example.com',
timeout: 5000,
headers
})
}

You will have to replace the baseURL value by the API provider base URL.

The function takes a token parameter which corresponds to the user's access token that Bearer manages to retrieve and stores for you as part of the OAuth flow.

Local Development

To simplify working with the API, OAuth integrations rely on a static access token when used in local development environment.

Once the authentication is configured (cf previously), you can generate an access token from the CLI:

NPM
Yarn
npm run bearer setup:auth
yarn bearer setup:auth

Next, you will be prompted to provide your OAuth credentials:

? Client ID: [hidden]
? Client secret: [hidden]

This should open up your browser, trigger the OAuth dance and return a static access token:

This will forwards it to the CLI and store it in the local.config.jsoncfile:

$ cat local.config.jsonc
{
"setup": {
"auth": {
"accessToken": "a0facb69f0a047c9b9475xxxxxxxxxxxxxx"
}
}
}%

This access token is automatically used by the event.context.auth.accessToken object in development, so you can build and test functions without having to trigger the OAuth dance.

Client(event.context.auth.accessToken).get('/an-endpoint')

Once the integration is deployed, you will provide your OAuth credentials in the Settings tab of the integration and the OAuth dance will be triggered by embedding a Connect Component (learn more).

Alternatively, you can ask your users to provide their own OAuth credentials by embedding a Setup Component (learn more).

Basic Auth

Configuration

When creating a Basic Auth based integration, the framework generates an authentication configuration file:

auth.config.json
{
"authType": "BASIC"
}

API Client

An API client is also configured by default:

functions/client.ts
import axios from 'axios'
export default function(username: string, password: string) {
const headers = {
'Accept': 'application/json',
'User-Agent': 'Bearer'
}
return axios.create({
baseURL: 'https://api.example.com/v1',
timeout: 5000,
auth: { username, password },
headers
})
}

You have to replace the baseURL value by the API provider base URL.

The function takes a username and password parameter that correspond to the user's credentials

Local Development

In local development, use the CLI to setup your (test) credentials:

NPM
Yarn
npm run bearer setup:auth
yarn bearer setup:auth
? Username: [input is hidden]
? Password: [input is hidden]

These credentials will be stored in the local.config.jsoncfile (git ignored by default):

$ cat local.config.jsonc
{
"setup": {
"auth": {
"username": "test",
"password": "test"
}
}
}%

These (test) credentials are automatically used by the event.context.auth.username and event.context.auth.passwordobjects in development, so you can build and test functions:

Client(event.context.auth.username, event.context.auth.password)
.get('/an-endpoint')

Once the integration is deployed, you can provide your API Key in the Settings tab of the integration or by embedding a Setup Component to let users provide their own (learn more).

API Key

Configuration

When creating an API Key based integration, the framework generates an authentication configuration file:

auth.config.json
{
"authType": "APIKEY"
}

API Client

An API client is also configured by default:

functions/client.ts
import axios from 'axios'
export default function(token: string) {
const headers = {
'Accept': 'application/json',
'User-Agent': 'Bearer',
'Authorization': token
}
return axios.create({
baseURL: 'https://api.example.com/v1',
timeout: 5000,
headers
})
}

You will have to replace the baseURL value by the API provider base URL.

The function takes a token parameter which corresponds to the API Key and forwards it to the API using an Authorization head.

Local Development

In local development, use the CLI to setup your (test) API key:

NPM
Yarn
npm run bearer setup:auth
yarn bearer setup:auth
? API Key: [hidden]

The API Key will be stored in the local.config.jsoncfile (git ignored by default):

$ cat local.config.jsonc
{
"setup": {
"auth": {
"apiKey": "XXXXXXXXXXXX"
}
}
}%

This (test) API Key is automatically used by the event.context.auth.apiKey object in development, so you can build and test functions:

Client(event.context.auth.token).get('/an-endpoint')

Once the integration is deployed, you can provide your API Key in the Settings tab of the integration or by embedding a Setup Component to let users provide their own (learn more).

NoAuth

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