Connecting Fusebit with Your Application

Now that you have a Fusebit Integration successfully sending messages to your integration target (Slack in this example), let's see how to connect your application to Fusebit! If you didn't complete the pre-requisite Getting Started guide, please check that out now.

At the end of this guide, you will have a working end-to-end experience where some action in your application results in a message being sent in Slack.

Obtain an Access Key

Communicating with the Fusebit APIs requires an Access KeyAccess Key - A long-lived key that you can use to invoke the Fusebit API. Simply provide the key as a bearer token in a the Authorization header of a request, as in `Authorization: Bearer {your-key}`. This key should be kept private and not shared, but can be revoked if necessary. to securely identify who you are, and protect your IntegrationIntegration - An integration is the place the you write your code to get things done! Written in NodeJS, an integration runs in Fusebit's secure and scalable environment to translate between the needs of your backend application and the remote service or services you're connecting to.s and ConnectorConnector - A connector is the package from Fusebit that manages the relationship between one or more integrations and a specific service. One of the most common types of connector is an OAuth connector, which takes care of the OAuth negotiation between your customers and the service you're integrating, so that you don't have to!s. You can obtain a Key from the Fusebit Management PortalFusebit Management Portal - The Fusebit Management Portal enables you to easily setup and manage all your integrations in one place. Link: https://manage.fusebit.io.

Go to the detail page for the Integration you created earlier and tap on the Connect button under Your Application.

On the next screen, you will be presented with your Key.

Be sure to take note of the following values as they will be used later on.

  • Key: it will only be displayed once for security reasons.
  • Integration Base URL: the root URL of your Integration's management endpoint

❗️

Access Keys are powerful authorization secrets that grant access to your Fusebit account. They do not expire, so store them securely.

This dialog also enables you to name the Key, so you can easily remember which system or application is invoking Fusebit using this Key.

Integration Installation

As appropriate in your solution, you will likely want to have a button that users press in order to install an Integration. Fusebit provides a set of endpoints that then guide a user through an authorization and configuration flow, ensuring they grant the right permissions in the third-party system, and supply any parameters the integration needs to correctly install. After this flow, the user will be returned to your application.

Users in your system are modeled as TenantTenant - A single user of an integration, usually corresponding to a user or account in your own system.s in Fusebit, and the system creates one InstallInstall - An install is a configured integration with a set of identity's and other values that represent a single user of the integration. You can search for instances by tags or by the special value of a Tenant (shh - it's also a tag, but don't tell anyone!). per Tenant as the following flow is completed.

  1. The first step is to start a SessionSession - A session is a sequence of steps that a user takes to configure a new integration, so that it can access their services on your behalf. You can think of a session as a combined task list and scratchpad - integrations will use a session to show forms and collect user data, and connectors will use a session to collect authentication credentials on behalf of the user. in response to the user of your application choosing to install the Integration. The API documentation for this call is here. The accessKey and integrationBaseUrl properties come from the previous screen. The tenantId field would normally be the ID you use in your system to identify the given user, but in this case let's hard-code that to user2. Here we assume you want to bring the user back to the same page of your application when the installation is done, so we capture its address as the redirectUrl.
const tenantId = 'user2';
const response = await superagent.post(`${integrationBaseUrl}/session`)
  .set('Authorization', `Bearer ${accessKey}`)
  .send({
    redirectUrl: `${window.location.origin}${window.location.pathname}`,
        tags: {
        'fusebit.tenantId': tenantId
      }
    });
const sessionId = response.body.id;
  1. Now that a Session has been created, the rest of the steps here will use that as a transient "property bag". This next step starts the Integration installation flow by navigating the browser to the configuration endpoint of the Integration. The user will see a series of screens where they will be required to authorize access to the third-party system (Slack) and provide any configuration parameters needed.
const configureUrl = `${integrationBaseUrl}/session/${sessionId}/start`;
window.location.href = configureUrl;
  1. When the user's browser returns to the redirectUrl specified in the first step, we need to kick off the creation of the Integration Install:
let result = await superagent.post(`${integrationBaseUrl}/session/${sessionId}/commit`)
  .set('Authorization', `Bearer ${accessKey}`)
  .send();
const { operationId } = result.body;
  1. Creation of an Integration Install is an asynchronous process. We can use the operationId returned in the previous step to poll until the Integration Install has been created.
// Wait up to 10s for the creation of the integration install to complete
const operationUrl = `${integrationBaseUrl.substr(0, integrationBaseUrl.indexOf('/integration/'))}/operation/${operationId}`;
for (let n = 0; n < 10; n++) {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  result = await superagent
    .get(operationUrl)
    .set('Authorization', `Bearer ${accessKey}`);
  if (result.statusCode === 200) {
    break;
  }
}

if (result.statusCode !== 200) {
  throw new Error('Timed out waiting 10s for the integration install to be initialized.');
}

// Install creation completed, get the Install
result = await superagent.get(`${integrationBaseUrl}/session/${sessionId}`)
  .set('Authorization', `Bearer ${accessKey}`);
const installId = result.body.output.entityId

Invoking the Integration Install

Now that installation for this Tenant is complete, you can invoke the Integration on their behalf. Fusebit will ensure their authorization and credentials will be used against the third-party system. The code below invokes the test endpoint of the Integration, identifying the intended tenantId as a segment of the URL. The content of the body is arbitrary and you can use it to pass any data you want from your application to the Integration logic.

await require('superagent')
  .post('${integrationBaseUrl}/api/tenant/${encodeURIComponent(tenantId)}/test')
  .set('Authorization', 'Bearer ${accessKey}')
  .send({
    tenantId: '${tenantId}',
    instanceId: '${installId}'
});

Access Key Management

Given that Access Keys are long-lived and provide access to your account in Fusebit, they should be handled with care. Here are some best practices around managing them:

  • Generate a unique Key for each isolated application or system that needs to call Fusebit
  • Give each Key a descriptive name to make it easy to track which application or system the key is meant to be used by
  • Remember that you can always delete a Key in the Your Application area of an Integration if you suspect it may have been compromised
  • You can implement an outage-free rollover from an old Key by generating a new one for the same system, and leaving both old and new Keys active for a brief window until all of your systems are migrated off the old Key.

📘

In some security scenarios, it is desirable to automatically roll Keys at a regular interval or use short-lived Access Tokens instead to minimize the chances of a credential being compromised. Fusebit supports these scenarios, please contact support for help on configuring them.