Pinecone provides a Connect widget that can be embedded into an app, website, or Colab notebook for a seamless sign up and login process. Through the widget, a user can sign up for or log in to Pinecone, select an organization and project, and generate an API key for the project. The widget then communicates the API key to the hosting page, app, or notebook. The widget displays as follows:

Connect widget

The Connect widget can be embedded multiple ways:

  • JavaScript library (@pinecone-database/connect): Renders the widget in apps and websites.
  • JavaScript script: Renders the widget in apps and websites.
  • React library (@pinecone-database/connect-react): Renders the widget in a React app.
  • Python library (pinecone-notebooks): Renders the widget in Colab notebooks.

If you do not want to use the embedded widget, you can use the ConnectPopup function in the JavaScript libary or script to bypass the widget and create a custom “Connect to Pinecone” button or link.

Your users can manage the API keys generated through the Connect widget on the API Keys tab in the Pinecone console.

Use the JavaScript library

To embed the Connect widget in your app or website, use the @pinecone-database/connect library:

Shell
# Install dependencies
npm i -S @pinecone-database/connect

You can use the JavaScript library to render the Connect widget and obtain the API key with one of the two following functions:

  • connectToPinecone: Displays the widget and calls the provided callback function with the Pinecone API key, once the user completes the flow.
  • getPineconeApiKey: Async function that displays the widget and returns the Pinecone API key in a promise.

It is also possible to skip rendering the widget and open the Connect flow popup directly:

  • ConnectPopup: Creates an object that can open the Connect flow in a popup window.

connectToPinecone function

The connectToPinecone function renders the Connect widget in an embedded context. Then, it calls the provided callback with the API key that results from the user completing the flow.

The function includes the following required configuration options:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a unique integrationId, register your app with Pinecone and become a partner.
  • container: The HTML element where the Connect widget will render.

Example:

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

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

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

getPineconeApiKey function

The getPineconeApiKey function renders the Connect widget in an embedded context, and waits for the user to complete the flow before returning the API key.

The function includes the following required configuration options:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a unique integrationId, register your app with Pinecone and become a partner.
  • container: The HTML element where the Connect widget will render.

Example:

JavaScript
import {getPineconeApiKey} from '@pinecone-database/connect'

const setupPinecone = async () => {
  const apiKey = await getPineconeApiKey({
    integrationId: 'myApp', 
    container: document.getElementById('widgetContainer')
  })
  /* Use the API key to initialize a Pinecone client */
}

ConnectPopup function

The ConnectPopup function creates an object that opens a popup for Pinecone users to login and generate an API key. This can be used to bypass the Connect widget and create a custom “Connect to Pinecone” button or link.

The function includes the following required configuration option:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a unique integrationId, register your app with Pinecone and become a partner.

The function returns an object containing the following:

  • open: A function that opens the popup. Suitable for use as an on-click handler.

Example:

JavaScript
<head>
...
<script src="https://connect.pinecone.io/embed.js"></script>
<script>
  const pineconePopup = ConnectPopup({
    onConnect: (key) => console.log(key),
    onCancel: () => console.log("Cancelled"),
    integrationId: 'myApp'
  });
</script>
...
</head>
<body>
...
<button onclick="pineconePopup.open()">Connect to Pinecone!</button>
...
</body>

Use the JavaScript script

To embed the Connect widget to your app or website, include the JavaScript script from connect.pinecone.io/embed.js.

You can use the JavaScript script to render the Connect widget and obtain the API key with one of the three following components:

  • connectToPinecone: Pre-built component that calls the provided callback with the API key that results from the user completing the flow.
  • getPineconeApiKey: Pre-built component that waits for the user to complete the flow before returning the API key.
  • ConnectPopup: Custom component that triggers a popup that allows Pinecone users to login and generate an API key.

connectToPinecone function

The connectToPinecone function renders the Connect widget in an embedded context. Then, it calls the provided callback with the API key that results from the user completing the flow.

The function includes the following required configuration options:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a unique integrationId, register your app with Pinecone and become a partner.
  • container: The HTML element where the Connect widget will render.

Example:

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

<div id="widgetContainer"></div>
...

<script>
  connectToPinecone(
    (apiKey) => {/* Use the apiKey to create an index*/}, 
    {
      integrationId: 'myApp', 
      container: document.getElementById('widgetContainer'),
    }
  );
</script>

...
</body>

getPineconeApiKey function

The getPineconeApiKey function renders the Connect widget in an embedded context and waits for the user to complete the flow before returning the API key.

The function includes the following required configuration options:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a unique integrationId, register your app with Pinecone and become a partner.
  • container: The HTML element where the Connect widget will render.

Example:

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

<div id="widgetContainer"></div>
...

<script>
  const apiKey = await getPineconeApiKey(
    {
      integrationId: 'myApp', 
      container: document.getElementById('widgetContainer')
    }
  );
  /* Use the API key to initialize a Pinecone client */
</script>

...
</body>

ConnectPopup function

The ConnectPopup function is a custom component that triggers a popup, that allows Pinecone users to login and generate an API key.

The function includes the following required configuration options:

  • integrationId: The slug assigned to the integration. If integrationId is not passed, the widget will not render.

    To receive a receive a unique integrationId, register your app with Pinecone and become a partner.

The function returns an object containing the following:

  • open: A function that opens the popup. Suitable for use as an on-click handler.

Example:

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

<button id="connectButton" disabled>Connect to Pinecone!</button>

<script>
/*  Define a function called connectWithAPIKey */
const connectWithAPIKey = () => {
  return new Promise((resolve, reject) => {
    /* Call ConnectPopup function with an object containing options */
    const popup = ConnectPopup({
      onConnect: (key) => {
        resolve(key);
      },
      integrationId: 'myApp'
    });
  });
};

/* Handle button click event */
document.getElementById('connectButton').addEventListener('click', () => {
  connectWithAPIKey()
    .then(apiKey => {
      console.log("API Key:", apiKey);
    })
    .catch(error => {
      console.error("Error:", error);
    });
});
</script>
...
</body>

Use the React library

To embed the Connect widget in your React app, use the @pinecone-database/connect-react library:

Shell
# Install dependencies
npm i @pinecone-database/connect-react

The library provides two components and a hook:

  • PineconeProvider: Wraps the section of your app that uses Pinecone. PineconeConnect and usePineconeApiKey usage must occur within a PineconeProvider component.

  • PineconeConnect: Renders the Connect widget. Accepts the following configuration option:

    • integrationId: The slug assigned to the integration. If an integrationId is not passed, the widget will not render.

      To receive a unique integrationId, register your app with Pinecone and become a partner.
  • usePineconeApiKey: Hook that returns the Pinecone API key, or null if the user has not yet configured the connection.

The following example demonstrates the usage of the above components and hook. Once the connection is configured, the API key is saved to its database and a thank you message is displayed:

import {PineconeConnect, PineconeProvider} from '@pinecone-database/connect-react';
import MyComponent from './MyComponent';

function App() {
  return (
    <PineconeProvider>
      <PineconeConnect integrationId="myApp" />
      <MyComponent />
    </PineconeProvider>
  );
}

export default App;

Use the Python library for Colab

To embed the Connect widget to your Colab notebook, use the pinecone-notebooks Python library:

Shell
# Install dependencies using Colab syntax

!pip install -qU pinecone-notebooks pinecone-client
Python
# Render the Connect widget for the user to authenticate and generate an API key
from pinecone_notebooks.colab import Authenticate

Authenticate()
Python
# The generated API key is available in the PINECONE_API_KEY environment variable
from pinecone import Pinecone, ServerlessSpec
import os

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

# Use the API key to initialize the Pinecone client
pc = Pinecone(api_key=api_key)

To see this flow in practice, see our example notebook.

Manage generated API keys

Your users can manage the API keys generated through the Connect widget in the Pinecone console:

  1. Open the Pinecone console.

  2. Select your project.

  3. Go to API Keys.

  4. Find the generated API key that was created by the Connect widget.

  5. Click the icons in the Action column of the generated API key to Show Key Value, Copy Key Value, Rotate Key Value, or Delete Key.

Was this page helpful?