​

Introduction

The Vessel API was designed to be set up quickly and effortlessly. However, if you get stuck or have trouble don’t hesitate to email us at support@vessel.dev.

​

Pre-requisites

Before diving into this guide, make sure to complete the following:

1. Create a free Vessel account and retrieve your development API key. Make sure to do the quick start tutorial as well before starting this!
2. Ensure you have access an account you can test on for an integration we support (e.g. Outreach, Mailchimp, Aircall, etc.). If you don’t have access to an account, we recommend signing up for a free Salesforce Developer account which will include access to the CRM and marketing APIs.

​

Setup

​

Step 1: Setting up the Auth UI

To start, we’ll use Vessel’s client sdk to quickly setup a front end component for authenticating your user’s tools. The client SDK adds a pre-built UI popup that walks your user through connecting to one of the many integrations we support.

1.1 Get the List of Supported Integrations

Vessel exposes a dedicated list integrations endpoint to help you build your integrations page UI. This endpoint returns all of the integrations we support as well as the name, high quality logo, and their integrationId.

export default function App() {
  const [integrations, setIntegrations] = useState([]);

  useEffect(() => {
    const getIntegrations = async () => {
      const res = await fetch("https://app.vessel.dev/api/integrations/list", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
      });
      const json = await res.json();
      setIntegrations(json.result.integrations);
    };
    getIntegrations();
  }, []);

  return (
    <div>
      <h1>Connect your Integrations</h1>
      {integrations?.map((integration) => (
        <button key={integration.integrationId}>
          <img src={integration.display.iconURI} />
          <h2>{integration.display.name}</h2>
        </button>
      ))}
    </div>
  );
}

1.2 Starting an Auth Session

If you’re using JavaScript or TypeScript you can install our Node SDK

npm i @vesselapi/sdk

An Auth session is a temporary session that holds state during the process of connecting to an integration. Any time a user wants to connect a new integration you must call this endpoint and start a new Auth session.

app.post("/session-token", async (req, res) => {
  const response = await fetch(
    "https://app.vessel.dev/api/auth/session-token",
    {
      headers: {
        "Content-Type": "application/json",
        "x-vessel-api-token": process.env.VESSEL_API_KEY,
      },
      method: "POST",
    }
  );

  const json = await response.json();
  res.json(json.result);
});

We’ll call this endpoint when invoking the modal in the next section.

1.3 Invoke the Auth Modal UI

Install the client SDK

npm i @vesselapi/client-sdk

Invoke the Vessel SDK and open the modal

import React, { useEffect, useState } from "react";
import Vessel from "@vesselapi/client-sdk";

export default function App() {
  const [integrations, setIntegrations] = useState([]);
  const { open } = Vessel(
    {
      onSuccess: () => console.log("success"),
      onLoad: () => console.log("loaded"),
      onClose: () => console.log("closed"),
    },
  );

  useEffect(() => {
    const getIntegrations = async () => { ... };
    getIntegrations();
  }, []);

  return (
    <div>
      <h1>Connect your Integrations</h1>
      {integrations?.map((integration) => (
        <button
          onClick={() =>
            open({
              integrationId: integration.id,
              getSessionToken: async () => {
                const response = await fetch("https://my-company.api/session-token", { method: "POST" });
                const json = await response.json();
                return json.sessionToken;
              },
            })
          }
          key={integration.integrationId}
        >
          <img src={integration.display.iconURI} />
          <h2>{integration.display.name}</h2>
        </button>
      ))}
    </div>
  );
}

1.4 (Optional) Configure Your OAuth App

If your plan supports white-labeling, you can configure an OAuth App for integrations that support OAuth to use your own branding and scopes instead of the Vessel default app.

To learn how to configure OAuth apps, please read the guide here.

1.5 Invoke the modal

Congrats 🎉! You should now be able to click on an integration and see the OAuth popup modal. If you click on the integration buttons and nothing happens or you see some other error, please reach out to support at support@vessel.dev.

​

Step 2: Making an API call

Now that you’re able to successfully start a session, let’s see how we can exchange our session token for an access token after the user has authenticated. The access token is what you’ll pass to our API (along with your api token) to make API calls.

2.1 Exchange the Session Token for an Access Token

Access Tokens are secrets and should be stored securely. It’s important to ensure access tokens are never exposed in the client or stored publicly.

Here’s an example of passing the session token to the backend. The logic is primarily contained in the onSuccess callback.

export default function App() {
  const [integrations, setIntegrations] = useState([]);
  const { open } = Vessel(
    {
      onSuccess: async (sessionToken) => {
        await fetch("https://my-company.api/access-token", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ sessionToken }),
        });
      },
      onLoad: () => console.log("loaded"),
      onClose: () => console.log("closed"),
    },
  );

  useEffect(() => {
    const getIntegrations = async () => { ... };
    getIntegrations();
  }, []);

  return (<div>{...}</div>);
}

Here’s an example of exchanging the session token that was passed for an access token

app.post("/access-token", async (req, res) => {
  const sessionToken = req.body.sessionToken;
  const response = await fetch("https://app.vessel.dev/api/auth/access-token", {
    headers: {
      "Content-Type": "application/json",
      "x-vessel-api-token": process.env.VESSEL_API_KEY,
      "x-vessel-session-token": sessionToken,
    },
    method: "POST",
  });

  const json = await response.json();
  const { connectionId, accessToken } = json.result;

  // !!IMPORTANT!! Make sure to store the connectionId and accessToken securely
  await saveToDb({ connectionId, accessToken });

  res.send({ success: true });
});

2.2 Call an API endpoint

You’re now ready to make an API call, feel free to browse one of the many unified or action APIs we support and pick one for the integration of the connection you just created.

Example: Get all Users from a connect sales engagement tool.

curl --location --request POST 'https://app.vessel.dev/api/unifications/engagement/users/list' \
--header 'x-vessel-api-token: [API_KEY]' \
--header 'x-vessel-access-token: [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{}'

​

Step 3: Managing Your Connections

It’s very important to make sure you only have active connections that you and your customers are actually using.

3.1 Listing Your Active Connections

To see which connections currently exist for your environments, you can call the connections/list endpoint with the api token for that environment.

Call the endpoint below to see the connection we just created, make sure to use your development api key.

curl --location --request POST 'https://app.vessel.dev/api/connections/list' \
--header 'x-vessel-api-token: [API_KEY]' \
--header 'x-vessel-access-token: [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{}'

3.2 Deleting a Connection

When your customer is done using a connection, you should be sure to delete the connection so that the resources are freed up.

curl --location --request POST 'https://app.vessel.dev/api/connections/delete' \
--header 'x-vessel-api-token: [API_KEY]' \
--header 'x-vessel-access-token: [ACCESS_TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{ "id": [CONNECTION_ID] }'

​

Feedback & Help

Did this process take you longer than an hour? If so, we want to hear about it. Please send an email to support@vessel.dev so we can inquire more about where we went wrong, what we need to improve, and how we can help.