Installing Konnect

How to install and start using Kolla Konnect in your user interface

When you are ready to embed integration management right in your user experience you can use the Kolla Embedded Marketplace. This allows you to have an integrations catalog and show connected status for each integration to your customers right in your user experience with only a few lines of code.

Add Konnect to Your Product

Installing Konnect requires two parts, one backend and one frontend.

Before using Konnect on your site you will need a way to verify users and share that information with Kolla. Kolla uses tokens to verify users from your application. Your application creates a consumer_token by hitting a Konnect API (backend code), and then passes that token to your frontend where it can be used by the Konnect Web SDK to show the marketplace and allow your users to connect their software to you.

1. Get the consumer_token (Backend Code)

First things first: head to the Kolla Admin Portal and go to Settings > API Keys and generate an API key for yourself.

Note that you won't be able to see that API key again, so put it somewhere safe

In your backend code, set up a POST request to get the consumer_token from this URL:

https://api.getkolla.com/connect/v1/consumers:consumerToken

This endpoint requires a unique identifier we call a consumer ID. The Consumer ID is an identifier you will use to identify this customer. Most of our customers use whatever ID they use in their own software for this ID.

It also allows you to pass in an optional consumer name which helps you identify your customer in our software with a human readable name.

Lastly, pass in your API key as a header.

Go

package main

import (
	"context"
	"log"
	"os"

	"github.com/kollalabs/sdk-go/kc"
)

func main() {
	// Get api key from environment variable
	apiKey := os.Getenv("KC_API_KEY")
	if apiKey == "" {
		log.Fatal("KC_API_KEY not set")
	}

	// Create a new client
	kolla, err := kc.New(apiKey)
	if err != nil {
		log.Fatalf("unable to create kolla connect client: %s\n", err)
	}

	// Get consumer token
	ctx := context.Background()
	consumerToken, err := kolla.ConsumerToken(ctx, "CONSUMER_ID", "CONSUMER_NAME")
	if err != nil {
		log.Fatalf("unable to get consumer token: %s\n", err)
	}

	log.Printf("ConsumerToken: %s\n", consumerToken)
}

Curl

curl --location --request POST 'https://api.getkolla.com/connect/v1/consumers:consumerToken'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer YOUR_API_TOKEN'
--data-raw '{ "consumer_id": "YOUR_CUSTOMER_ID", "metadata": { "username": "OptionalUsername", "email": "OptionalEmail", "tenant_id": "OptionalCompanyID", "tenant_display_name": "OptionalCompanyName" } }'

Now that you have the consumer_token, you will need to pass it to the frontend of your application to use in the embedded marketplace. For single page apps, you will need to write your own API endpoint to get it to the front-end. For server-side rendered pages you can add it to the rendered HTML in a <script> tag.

2. Show the Marketplace (Frontend Code)

On your frontend, use the Web SDK and the consumer_token you created on the backend to show the marketplace. First, include the Web SDK in your app by putting the following script tag in the head section of your web app:

<script type="text/javascript" src="https://cdn.getkolla.com/sdk/v1/index.js"></script>

When installed it will put the kolla object in the global window scope for you to reference.

Next, authenticate with the consumer token you generated in section 1:

kolla.authenticate("CONSUMER_TOKEN_GOES_HERE")

Then open the embedded marketplace modal with one simple command:

kolla.openMarketplace();

Your customer chooses an integration from the marketplace and follows the instructions to connect their account to you.

Check out the other capabilities of the Web SDK in the full reference

3. Access tokens or credentials from your backend

Once your customer has finished connecting their account, you can access data from the connected app by getting your customers access token from the Kolla API.

Let's take the Slack connector as an example. After your customer connects their Slack account to you, Konnect stores and refreshes the Slack OAuth2 token for you. When you want to use the Slack API for your customer's Slack account, your backend code gets the Slack token from the Konnect API and then uses that token to hit the Slack API. Here are some code examples of what that could look like:

Go

package main

import (
	"context"
	"os"

	"github.com/kollalabs/sdk-go/kc"
	"github.com/slack-go/slack"
)

func main() {
	// Get api key from environment variable
	apiKey := os.Getenv("KC_API_KEY")
	// Create a new client
	kolla, err := kc.New(apiKey)
	if err != nil {
		log.Fatalf("unable to create kolla connect client: %s\n", err)
	}

	ctx := context.Background()
	creds, err := kolla.Credentials(ctx, "slack", "CONSUMER_ID")
	if err != nil {
		panic(err)
	}
	//creds.LinkedAccount.AuthData
	slackapi := slack.New(creds.Token)
	_, _, err = slackapi.PostMessage("general", slack.MsgOptionText("Hello world! (Sent with Kolla managed token)", false))
	if err != nil {
		panic(err)
	}
}

Curl

curl --location --request POST 'https://api.getkolla.com/connect/v1/connectors/CONNECTOR_ID/linkedaccounts/-:credentials' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
  "consumer_id": "YOUR_CUSTOMER_ID"
}'