Integration Clients

Bearer's clients are here to facilitate the integrations for your app. These Clients are available for server-side (NodeJS, Ruby etc.) and client-side (Javascript, React) context. The server-side clients let you: - Call functions - Receive, decrypt and acknowledge webhooks The client-side ones let you: - Call functions - Create a Connect Component (for OAuth) - Create a Setup Component

Server-side

Installing & Initializing

Node.js
Express.js
Rails
Ruby
npm install @bearer/node
npm install @bearer/node
# For WebHooks
npm install @bearer/express
gem install bearer-rails
gem install bearer

Initialize the client:

Node.js
Express.js
Rails
Ruby
import bearer from '@bearer/node'
const bearerClient = bearer(process.env.BEARER_API_KEY)
import bearer from '@bearer/node'
const bearerClient = bearer(process.env.BEARER_API_KEY)
//For WebHooks
import bearerWebhooks from '@bearer/express'
const EncryptionKey = process.env.BEARER_ENCRYPTION_KEY
# in config/initializers/bearer.rb
Bearer::Configuration.setup do |config|
config.api_key = BEARER_API_KEY
config.secret = BEARER_ENCRYPTION_KEY ## Used for the WebHook
end
# in config/routes.rb
Rails.application.routes.draw do
# ...
mount BearerRails::Webhooks.new, at: '/bearer-webhooks'
end
Bearer::Configuration.setup do |config|
config.api_key = BEARER_API_KEY
end

Replace the BEARER_API_KEY and BEARER_ENCRYPTION_KEY respectively with your API Key and Encryption Key respectively that can be found on your Developer Keys page.

Calling Functions

Node.js
Ruby
bearerClient.invoke('INTEGRATION_UUID', 'FUNCTION_NAME', {
query: { params: 'value' }
})
.then(() => {
console.log('Successfully invoked function')
})
.catch(() => {
console.log('Something went wrong')
})
Bearer.invoke(
"INTEGRATION_UUID",
"FUNCTION_NAME",
params: { params: "value" }
)

Receiving Webhooks

Express.js
Rails
const webhookHandlers = {
['INTEGRATION-UUID']: req =>
new Promise(() => {
// you logic goes here
if (something) resolve()
else {
reject()
}
})
}
app.use('/bearer-webhooks', bearerWebhooks(webhookHandlers, { token: EncryptionKey }))
# in app/webhooks/my_handler.rb
class MyHandler
include BearerRails::Webhook
integration_handler "INTEGRATION_UUID"
def call
consume_webhook_service(body)
end
end

Client-side

Installing & Initializing

JavaScript
React
// With a NPM
npm install @bearer/js
// Without NPM
<script src="https://cdn.jsdelivr.net/npm/@bearer/js/lib/bearer.production.min.js"></script>
npm install @bearer/react

Initialize the client:

JavaScript
React
// With NPM
import bearer from '@bearer/js'
// Without NPM
const bearerClient = bearer('BEARER_CLIENT_ID')
import * as React from 'react'
import { Bearer } from "@bearer/react"
const App = () =>
<Bearer clientId="BEARER_CLIENT_ID">
<MyComponent />
</Bearer>

Replace the BEARER_CLIENT_ID with your Client ID that can be found on your Developer Keys page.

Calling Functions

JavaScript
React
bearerClient.invoke('INTEGRATION_UUID', 'FUNCTION_NAME', {
query: { params: 'value' }
})
.then(() => {
console.log('Successfully invoked function')
})
.catch(() => {
console.log('Something went wrong')
})
import * as React from "react"
import { BearerContext } from "@bearer/react/lib/bearer-provider"
const MyComponent = () => {
const context = useContext(BearerContext);
const handleClick = (e: any) => {
context.bearer
.invoke("INTEGRATION_UUID", "FUNCTION_NAME", { query: { params: "value" } })
.then(data => { console.log(data) })
.catch(console.error);
}
return (
<button type="button" onClick={this.handleClick}>Click Me</button>
)
}

Create a Connect Component

In the case of OAuth integration, you need to create a Connect Component (less fancy, just a button) on your app, so that users can trigger the OAuth dance and retrieve their access token.

JavaScript
React
bearerClient.connect(
'INTEGRATION_UUID',
'YOUR_SETUP_ID',
{ authId: 'YOUR_USER_IDENTIFIER' }
)
import * as React from "react"
import { factory } from "@bearer/react"
import { BearerContext } from "@bearer/react/lib/bearer-provider"
const { Connect } = factory(INTEGRATION_UUID);
const MyComponent = () => {
const [authId, setAuthId] = React.useState();
return (
<Connect authId={YOUR_USER_IDENTIFIER} setupId={YOUR_SETUP_ID}
onSuccess={data => {
setAuthId(data.authId);
}}
render={({ connect }) => {
return (
<button onClick={connect}>Connect</button>
)
}}
/>
)
}

Replace YOUR_SETUP_ID with the Setup Identifier holding your OAuth credentials. You can fill in those credentials directly in the Settings page of your integration and get a Setup ID:

Replace YOUR_USER_IDENTIFIER with your app current user's UUID. This way, Bearer can securely store your user OAuth token by referencing their uuid so you can easily be able to call your functions. Your app doesn't need to store anything.

Security first! Make sure to use an unguessable user identifier, such as a UUID. Don’t let malicious users call your function using someone else’s identity.

If you don't provide an authId value, Bearer will automatically generate one for you and will return it as a Javascript event. You will have to store this somewhere.

Create a Setup Component

By default, you are able to provide your API credentials in the Settings page of the integration.

If you need to ask your users to provide their own, you can easily create a Setup Component on your app.

When they provide their credentials, Bearer will store them and provide in exchange a Setup Id that will then be needed to query your functions.

Here is an example of a Setup Component for an API Key based integration:

JavaScript
React
React (HOC)
<script src="https://cdn.jsdelivr.net/npm/@bearer/js/lib/bearer.production.min.js"></script>
<script>
const bearerClient = bearer('BEARER_CLIENT_ID')
function submitHandler(e) {
bearerClient
.invoke('INTEGRATION_UUID', 'bearer-setup-save', {
apiKey: document.querySelector('form').elements[0].value
})
.then(console.log)
.catch(console.error)
return false
}
</script>
<form action="#">
<input type="string" name="apiKey" />
<button type="submit" onclick="submitHandler()">Save</button>
</form>
import * as React from "react"
import { BearerContext } from "@bearer/react/lib/bearer-provider"
const MyComponent = () => {
const [setupId, setSetupId] = React.useState();
const context = useContext(BearerContext);
const handleClick = (e: any) => {
context.bearer
.invoke("INTEGRATION_UUID", "bearer-setup-save", { apiKey: "value" })
.then(data => { setSetupId(data.setupId); })
.catch(console.error);
}
return (
<button type="button" onClick={this.handleClick}>Click Me</button>
)
}
// Using https://reactjs.org/docs/higher-order-components.html
import * as React from "react"
import { BearerContext } from "@bearer/react/lib/bearer-provider"
const { withInvoke } = factory(INTEGRATION_NAME)
const withSetupSave = withInvoke("bearer-setup-save")
const MyComponent = (props) => {
const [setupId, setSetupId] = React.useState();
const context = useContext(BearerContext);
const handleClick = (e: any) => {
props.invoke({ apiKey: "value" });
}
return (
<button type="button" onClick={this.handleClick}>Click Me</button>
)
}
export default withSetupSave(MyComponent);

As you can see, it's basically just a call to the bearer-setup-save function, provided with every integration by default.