Embedding the Integration Hub

Integrating multiple services into your web app is now easier with the StackOne Hub, which provides a streamlined way for your customers to authenticate and configure the integrations enabled in your StackOne projects.

This guide will walk you through the process of embedding the StackOne Hub into your application whether you’re using React (via the @stackone/react-hub package) or by using directly the underlying StackOne “Connect” library.

Step 1: Install the StackOne React Hub Package

First, add the @stackone/react-hub package to your project using either npm or yarn

Using npm

npm install --save @stackone/react-hub

Using Yarn

yarn add @stackone/react-hub

Step 2: Implement a function to retrieve the connect session token

The React Hub needs to retrieve a connect session token to be able to securely communicate with the StackOne Portal. This is achieved by making a POST request to StackOne API /connect_sessions endpoint.

Since this involves sending the API Key and other sensitive data, the recommended approach is to make this request through your application backend avoiding the need for exposing credentials in the frontend code.

As an example, assuming that the application backend already has that endpoint a function to retrieve the connection session token could be as simple as:

javascript
export const retrieveConnectSessionToken = async ({ username, provider }) => {
  const payload = {
    originUsername: username, // eg: jane@customer.com (the username trying to connect)
    provider, // optional - (specifying a provider will make the stackone hub load directly the  provider's connection screen and bypass the integrations listing screen)
  };

  const headers = {
    'Content-Type': 'application/json',
  };

  const connectSessionResponse = await fetch(
    'https://your-application.com/stackone_connect_session', // your back-end implementation for forwarding the request with the relevant API key to StackOne's /connect_sessions endpoint
    {
      method: 'POST',
      headers,
      body: JSON.stringify(payload),
    },
  );

  const response = await connectSessionResponse.json();

  return { token: response.token };
};

This example is only calling the endpoint that will communicate with the StackOne API and getting the token from the response so that it can be used in the react hub hook in the next step.

For instructions on how to build the backend endpoint that communicates with the StackOne API please refer to the guide to connect your backend with StackOne API.

Customising the hub behaviour

Per the Connect Sessions documentation and the associated back-end implementation example Connect your Backend with StackOne, you can specify a provider property so the integration hub will directly filter or load the given provider or category instead of displaying a list of all integrations enabled.

Step 3: Create a Link Account Button

Create a button component that users can click to link their accounts. The button will utilize the useStackOneHub hook to initiate the Connect flow.

Typescript
import { useStackOneHub } from '@stackone/react-hub';

const LinkAccountButton = () => {
  const { startConnect } = useStackOneHub();

  const startFlow = useCallback(async () => {
    const sessionToken = await retrieveConnectSessionToken({ username: 'jane@example.com' });
    startConnect({ sessionToken });
  }, [startConnect]);

  return (
    <button onClick={startFlow}>Connect Account</button>
  );
};

Your application is now ready to start connecting accounts!

Step 1 - install the connect script

You should insert the a script tag wherever you intend to display the StackOne hub.

This can be done one of two ways

Adding the following script in the <body> of your page:

HTML
<script src="https://app.stackone.com/stackone/connect.js"></script>

Alternatively you can also add the script tag via javascript, for example via the following code:

const script = document.createElement('script');
script.src = 'https://app.stackone.com/stackone/connect.js';
document.body.appendChild(script);

Step 2 - Implement the function to generate a session token

To use the Connect library, you will also need to generate a session token. Refer to the documented step here.

Step 3 - Use the connect library

JavaScript

const connectSessionToken = await retrieveConnectSessionToken();

// The code below will open the StackOne Hub
// Depending on the session token generated - the hub can be opened on the listing page or directly on the set-up screen of a specified provider.
// The onSuccess callback will be called if the user interacting with the StackOne Hub sucessfully links an account
Connect.start({
  sessionToken: connectSessionToken,
  onSuccess: (e) => {
    console.log('> stackone - new account linking', e);
  }
});

You can add hub styling to the start options via the styles property:

Typescript
// Example of styles object
const styles = {
  inline: { // Removes the dropshadow and z-index from the iframe
    containerId: 'my-container-id', // Your page container where the iframe will be appended to
    height: '500px', // Height of the Hub
    width: '300px', // Width of the Hub
  },
  options: {
    back: false, // Removes the back arrow from the Hub
    close: false, // Removes the close button from the Hub
    bgColor: 'white', // The background color of the Hub (This only changes the background,
    									// the font color will remain the same, so be aware of that)
  },
};

Default look of the Hub

Customised Style Hub (with Inline and custom width)

This can be very helpful if you want the hub to be inline on your page, disable back/close buttons, etc. All of these properties are optional so you can customize the best user experience for your users.

Generating a connect session token

Connecting with the StackOne API must be done server-side. This is required to keep your API keys secure and prevent them from being exposed in the frontend code.

You will need a StackOne API Key to successfully request a token via the Connect Sessions Endpoint.

When using the API to generate the connect session token, several supported scenarios exist. The fields origin_owner_id and origin_owner_name are required, while origin_username is optional. If the origin_owner_id, origin_owner_name, and provider have been used previously, the existing account will be updated; otherwise, a new account will be created.

Additionally, you can add the following fields to control the behavior of the connect session token.

Field	Description
label	A label is a text field that can be used to store any string data against the account
category	The hub page will open at the category selector (HRIS, ATS etc) where the user can go through the remaining steps to complete adding the new account.
provider	The Hub page will open directly at the final stage where the user can enter the credentials and complete the last steps to complete adding the new account.
account_id	If an existing account id is included in the connect session then the hub will open on the Edit Account page where the credentials can be updated and the account can be re-linked

The following code demonstrates a basic implementation with all the required parameters:

app.post('/stackone_connect_sessions', jsonParser, async (req, res) => {
  const STACKONE_API_KEY = 'YOUR_STACKONE_API_KEY';

  const headers = {
    Authorization:
      'Basic ' + Buffer.from(STACKONE_API_KEY + ':' + '').toString('base64'),
  };

  // optional - metadata to be associated with the connection
  const metadata = { source: 'my-backend' };

  const { originUsername, provider } = req.body;

  const payload = {
    origin_owner_id: 'customer-123', // The organization id of the customer in your system
    origin_owner_name: 'Acme Inc', // The organization name to easily identify the owner of the connected account in StackOne
    origin_username: originUsername, // eg: 'jane@customer.com' - an identifier for the user initiating the connection
    provider,
    metadata,
  };

  const requestOptions = {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...headers,
    },
    body: JSON.stringify(payload),
  };

  try {
    const responseWithToken = await fetch(
      'https://api.stackone.com/connect_sessions',
      requestOptions,
    );
    const { token } = await responseWithToken.json();
    res.send({ token });
  } catch (e) {
    res.status(500).send('error when trying to fetch session');
  }
});

If the combination of origin_owner_id and origin_owner_name for a given provider has not previously been used this will create a new Account. If the origin_owner_id and origin_user_name values have already been used for a given provider then the existing account will be updated.

In summary, the endpoint will send a POST request to the StackOne API /connect_sessions endpoint with the credentials and the request data. If the request is successful, it will respond with an object that contains a token property. This token will be returned and can then be used by the frontend to connect the React Hub with your application. When the frontend process is completed an Account will either be created or updated.

The origin_owner_id should always be set via server-side logic and not be passed through directly via the client-side request.

For most scenarios the simple use case described above should meet all requirements. To support some more advanced use cases we have introduced a new multiple flag. The multiple flag allows more control over the upsert behaviour on Accounts. In the simple use case above we saw how using an unused combination of origin_owner_id and origin_owner_name for a given provider would create a new Account but if we reused those values or specified an existing account_id then the existing account would be updated.

In some limited use cases you may wish to have multiple connected accounts for a given provider that are configured with the same origin_owner_id and origin_owner_name. If this behaviour is desired then you need to pass the _multiple_ flag set to true when the Connect Session is created. If the multiple flag is set then then any existing account with the same settings will be left untouched and a new account will be created.

Fields	Details Used Before?	Description	Account Action
`origin_owner_id` `origin_user_name` `origin_name` `category` (optional) `provider` (optional)	No	A new account will be created. If the `category` is specified, the hub will open in the provider selection screen; otherwise, it will open with the selected provider.	Create
`origin_owner_id` `origin_user_name` `origin_name`	Yes	The existing account will be opened in edit mode.	Update

Customising the hub behaviour

Per the Connect Sessions documentation, you can also specify a provider or categoriesproperty so the integration hub will directly filter or load the given integration (provider) or categories.

The values accepted in the provider property can be found in the Supported Providers list in the Provider Key column.

If the provider is left undefined, the StackOne integrations hub will display a list of all integrations enabled for the project associated with the given API key.

Any provider specified when generating the connect session token must be enabled in the integrations page of the associated project.

Integrate with StackOne

StackOne Dashboard

StackOne API

Embedding the Integration Hub

Step 1: Install the StackOne React Hub Package

Using npm

Using Yarn

Step 2: Implement a function to retrieve the connect session token

Customising the hub behaviour

Step 3: Create a Link Account Button

Step 1 - install the connect script

Step 2 - Implement the function to generate a session token

Step 3 - Use the connect library

Default look of the Hub

Customised Style Hub (with Inline and custom width)

Generating a connect session token

Customising the hub behaviour

Integrate with StackOne

StackOne Dashboard

StackOne API

Step 1: Install the StackOne React Hub Package

Using npm

Using Yarn

Step 2: Implement a function to retrieve the connect session token

Customising the hub behaviour

Step 3: Create a Link Account Button

Step 1 - install the connect script

Step 2 - Implement the function to generate a session token

Step 3 - Use the connect library

Default look of the Hub

Customised Style Hub (with Inline and custom width)

​Generating a connect session token

Customising the hub behaviour

Generating a connect session token