Connect your users to Pinecone

Add a Connect to Pinecone flow to your app, website, or Colab notebook so your users can get a Pinecone API key without leaving your integration. In the flow, users sign up for or log in to Pinecone, select or create an organization and project, and generate an API key. The API key is then shown to the user to copy, or sent directly to your page, app, or notebook. You can add the flow in two ways:

Add a Connect popup that opens from your own button or link.
Embed the Connect widget, a drop-in component with the same functionality.

Both require an integration ID, so start by creating one.

Only organization owners can add or manage integrations.

Create an integration ID

Create a unique integrationId to use with the Connect to Pinecone popup and widget:

Open the Integrations tab

On the Integrations tab in the Pinecone console, click Create Integration.

The Integrations tab doesn’t appear until your organization has an integration. To create your first one, go to the Create integration form directly.

Fill out the form

In the Create integration form, fill out these fields:

Integration name: A name for your integration.
URL Slug: Your integrationId. Enter a human-readable string that uniquely identifies your integration and that may appear in URLs. The URL slug is public and can’t be changed.
Logo: A logo for your integration.
Return mechanism: How the generated API key is returned:
- Web Message: Your application receives the API key through a web message, and only the allowed origins you list below receive it. Select this option if you use the @pinecone-database/connect library.
- Copy/Paste: The API key appears in the success message, and users copy and paste it into your application.
Allowed origin: If you selected Web Message, list the URL origins where your integration is hosted. An origin is the part of a URL that specifies the protocol, hostname, and port.

Create the integration

Click Create.

After you create your integration, attribute usage to your integration.

Anyone can create an integration. To apply to become an official Pinecone partner, see Integration ecosystem.

After you create your integrationId, you can open the Connect to Pinecone popup from your own button or link. You can use the JavaScript library or the script. The library is the most common method. Use the script when you can’t build with a custom library, such as in a content management system (CMS).

Load the library or script

Install the @pinecone-database/connect library, or load the script in your page’s <head>:

npm i -S @pinecone-database/connect

<script src="https://connect.pinecone.io/embed.js"></script>

Create the popup

Call the ConnectPopup function. It takes one required configuration option:

integrationId: The URL slug of your integration. If you don’t pass integrationId, the popup doesn’t render.

When the user completes the flow, the onConnect callback receives the API key. The function returns an object with an open function that opens the popup.

import { ConnectPopup } from '@pinecone-database/connect'

const popup = ConnectPopup({
  onConnect: (key) => console.log("API Key:", key),
  integrationId: 'myApp'
});

<script>
  const pineconePopup = ConnectPopup({
    onConnect: (key) => console.log(key),
    onCancel: () => console.log("Cancelled"),
    integrationId: 'myApp'
  });
</script>

Open the popup from your button or link

Call open when the user clicks your button or link:

document.getElementById('connectButton').addEventListener('click', () => {
  popup.open();
});

<button onclick="pineconePopup.open()">Connect to Pinecone</button>

The Connect widget is a drop-in component with the same functionality as the popup. After you create your integrationId, you can embed it in two ways:

Use the JavaScript library (@pinecone-database/connect) or script to render the widget in apps and websites.
Use the Colab library (pinecone-notebooks) to render the widget in Colab notebooks with Python.

JavaScript

To embed the widget in your app or website, use the @pinecone-database/connect library or, if you can’t use the library, the script.

Load the library or script

Install the library, or load the script in your page’s <head>:

npm i -S @pinecone-database/connect

<script src="https://connect.pinecone.io/embed.js"></script>

Add a container for the widget

Add the HTML element where the widget renders:

HTML

<div id="connect-widget"></div>

Render the widget

Call the connectToPinecone function. It takes two required configuration options:

integrationId: The URL slug of your integration. If you don’t pass integrationId, the widget doesn’t render.
container: The HTML element where the widget renders.

When the user completes the flow, the function calls your callback with the Pinecone API key. If you use the script, place the inline <script> in the page body after the container element, so the container exists when connectToPinecone runs.

import { connectToPinecone } from '@pinecone-database/connect'

const setupPinecone = (apiKey) => { /* Set up a Pinecone client using the API key */ }

connectToPinecone(
  setupPinecone,
  {
    integrationId: 'myApp',
    container: document.getElementById('connect-widget')
  }
)

<script>
  connectToPinecone(
    (apiKey) => { /* Set up a Pinecone client using the API key */ },
    {
      integrationId: 'myApp',
      container: document.getElementById('connect-widget'),
    }
  );
</script>

Colab

To embed the widget in a Colab notebook, use the pinecone-notebooks Python library.

Install the libraries

pip install -qU pinecone-notebooks pinecone[grpc]

Render the widget

Call Authenticate to render the widget, so the user can log in and generate an API key:

from pinecone_notebooks.colab import Authenticate

Authenticate()

Use the API key

After the user completes the flow, the API key is available in the PINECONE_API_KEY environment variable. Use it to initialize the Pinecone client:

import os
from pinecone.grpc import PineconeGRPC as Pinecone

pc = Pinecone(api_key=os.environ.get('PINECONE_API_KEY'))

To see this flow in practice, open the example notebook.

Manage generated API keys

Your users can manage the API keys generated by your integration in the Pinecone console.

Connect an integration

Build an integration

Connect your users to Pinecone

Create an integration ID

Embed the Connect widget

JavaScript

Colab

Manage generated API keys

​Create an integration ID

​Add a Connect popup

​Embed the Connect widget

​JavaScript

​Colab

​Manage generated API keys

Create an integration ID

Add a Connect popup

Embed the Connect widget

JavaScript

Colab

Manage generated API keys