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.

​

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.

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.