Fusebit allows you to attach tags to Integrations, Connectors, Installs, and Identities. These tags are used to associate additional information with an item as well as allow you to search your items by these values.

Integration and Connector Tags

Integrations and Connectors can be given tags using either the Fusebit API or by supplying tags within the associated fusebit.json file.

{
  "handler": "./integration",
  "components": [],
  "componentTags": {},
  "configuration": {},
  "tags": {
    "exampleTagKey": "exampleTagValue"
  }
}

curl --request POST \
     --url https://api.us-west-1.on.fusebit.io/v2/account/${ACCOUNT_ID}/subscription/SUBSCRIPTION_ID/integration/INTEGRATION_ID \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "tags": {
          "exampleTagKey": "exampleTagValue"
     }
}
'

These tags can then be passed to the corresponding Fusebit API GET endpoint in order to search for all Integrations or Connectors that contain a matching tag.

curl --request GET \
     --url 'https://api.us-west-1.on.fusebit.io/v2/account/${ACCOUNT_ID}/subscription/${SUBSCRIPTION_ID}/integration?tag=exampleTagKey%3DexampleTagValue' \
     --header 'Accept: application/json'

Tag names and values are arbitrary strings you control. However, tag names with the fusebit. prefix are reserved for tags defined by the Fusebit Platform. One such tag is fusebit.tenantId described later.

Install and Identity Tags

Installs and Identities can be given tags and searched by tags in the same manner as Integrations and Connectors. However, because Installs and Identities are created dynamically during an authorization flow, it is often desirable to apply tags to these components dynamically by either supplying them to the Session when beginning a tenant's installation process, or by inheriting desired tags from the given Integration.

Applying Tags using Sessions

When you create a session for a new Integration Install, you may pass any number of tags to the session endpoint. For example, you might wish to provide a tag to denote the type of subscription plan a tenant has within your system, or the registration date of the tenant. To do so, you would provide a tag during the session creation, as so;

const tenantId = 'user2';
const tenantPlan = 'Platinum Pro';
const registrationDate = '2020-01-01';

const response = await superagent.post(`${integrationBaseUrl}/session`)
  .set('Authorization', `Bearer ${accessKey}`)
  .send({
    redirectUrl: `${window.location.origin}${window.location.pathname}`,
    tags: {
      'fusebit.tenantId': tenantId,
      'tenantPlan': tenantPlan,
      'registrationDate': registrationDate
    }
  });
const sessionId = response.body.id;

These provided tags will propagate as your tenant navigates the installation process. When the session is committed, these tags will be applied to the resulting Install and any associated Identities.

For a detailed explanation of the core concepts of the session creation and commit process, view the Connecting Fusebit with Your Application documentation.

Extending Tags From Integrations

In addition to supplying tags during session creation, you may also provide a default list of tags on an integration, to be used when future Installs and Identities are created. To do so, add the desired tags to the componentTags object inside the fusebit.json file of the integration. You may alternately choose to update this value via the integration POST or PUT endpoints of the Fusebit API. To do so, supply the desired tags to the data.componentTags attribute.

{
  "handler": "./integration",
  "components": [],
  "componentTags": {
    "componentTagKey": "Key applied to installs and identities of this integration"
  },
  "configuration": {},
  "tags": {
    "integrationTagKey": "Key used to search integrations"
  }
}

curl --request POST \
     --url https://api.us-west-1.on.fusebit.io/v2/account/${ACCOUNT_ID}/subscription/SUBSCRIPTION_ID/integration/INTEGRATION_ID \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
        "data": {
      "componentTags": {
        "componentTagKey": "Key applied to installs and identities of this integration"
      },
    }
    "tags": {
      "integrationTagKey": "Key used to search integrations"
    }
}
'

To apply these tags to an Install, simply set the extendTags flag when creating a new session:

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
    },
    extendTags: true
  });
const sessionId = response.body.id;

Doing this will apply the tags from the Integration's componentTags to both the Install and associated Identities.

If a tag is provided to a session which also exists on the Integration's componentTags, the session's tag value will be prioritized.

TenantId Tag

Sessions are commonly provided a tag with a key of fusebit.tenantId. This tag is used to associate an Install and Identity with a specific tenant of your application by setting its value to an identifier representing that tenant. This tag should be unique for each Install of an Integration, and is therefore recommended that it be excluded from the Integration's extendable componentTags.

The value of the fusebit.tenantId tag can be later used within your integration code to create an authenticated SDK that allows you to make calls to a target system like Slack or HubSpot on behalf of a specific tenant of your application.

integration.get('/api/:tenantId', async (ctx) => {
  // tenantId provided as the `fusebit.tenantId` tag when creating the integration session
  const connectorSdk = integration.tenant.getSdkByTenant(ctx, 'componentName', ctx.params.tenantId);
});