Skip to main content
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 there are a few different supported scenarios. The origin_owner_id and origin_owner_name are required fields but the origin_username is optional. If the origin_owner_id, origin_owner_name and provider have been used before then the previously created account will be updated otherwise a new account will be created. Additionally, you can add the following fields to control the behaviour of the connect session token.
FieldDescription
labelA label is a text field that can be used to store any string data against the account.
categoryThe 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.
providerThe 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_idIf 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: 
import { StackOne } from "@stackone/stackone-client-ts";

const stackOne = new StackOne({
  security: {
    username: process.env.STACKONE_API_KEY,
    password: "",
  },
});

app.post('/stackone_connect_sessions', async (req, res) => {
  const { originUsername, provider } = req.body;

  try {
    const result = await stackOne.connectSessions.createConnectSession({
      originOwnerId: "customer-123", // The organization id of the customer in your system
      originOwnerName: "Acme Inc", // The organization name to identify the account in StackOne
      originUsername: originUsername, // eg: '[email protected]' - identifier for the user initiating the connection
      provider,
      metadata: { source: "my-backend" }, // optional - metadata to associate with the connection
    });

    res.send({ token: result.connectSessionTokenAuthLink?.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.

​
Advanced Use Case

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.
FieldsDetails Used Before?DescriptionAccount Action
origin_owner_id origin_user_name origin_name category (optional) provider (optional)NoA 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_nameYesThe existing account will be opened in edit mode.Update

​
Customizing the Hub Behavior