Connect to Pinecone with an embedded widget

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 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.

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:

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

There are two alternative functions for rendering the Connect widget and obtaining the API key:

• connectToPinecone: Calls the provided callback with the API key that results from the user completing the flow.
• getPineconeApiKey: Waits for the user to complete the flow before returning the 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 accepts the following configuration options:

• integrationId: The slug assigned to the integration. If integrationId is not passed, it will display as [unknown app].

  To register your app with Pinecone and receive a unique integrationId, become a partner. Unregistered apps have limited functionality and appear as [unknown app] to the user.

• container: The HTML element where the Connect widget will render. If the container is not passed, the button will be rendered as part of document.body.

Example:

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 accepts the following configuration options:

• integrationId: The slug assigned to the integration. If integrationId is not passed, it will display as [unknown app].

  To register your app with Pinecone and receive a unique integrationId, become a partner. Unregistered apps have limited functionality and appear as [unknown app] to the user.

• container: The HTML element where the Connect widget will render. If the container is not passed, the button will be rendered as part of document.body.

Example:

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 */
}

​

Use the JavaScript script

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

There are two alternative functions for rendering the Connect widget and obtaining the API key:

• connectToPinecone: Calls the provided callback with the API key that results from the user completing the flow.
• getPineconeApiKey: Waits for the user to complete the flow before returning the 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 accepts the following configuration options:

• integrationId: The slug assigned to the integration. If integrationId is not passed, it will display as [unknown app].

  To register your app with Pinecone and receive a unique integrationId, become a partner. Unregistered apps have limited functionality and appear as [unknown app] to the user.

• container: The HTML element where the Connect widget will render. If the container is not passed, the button will be rendered as part of document.body.

Example:

<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 accepts the following configuration options:

• integrationId: The slug assigned to the integration. If integrationId is not passed, it will display as [unknown app].

  To register your app with Pinecone and receive a unique integrationId, become a partner. Unregistered apps have limited functionality and appear as [unknown app] to the user.

• container: The HTML element where the Connect widget will render. If the container is not passed, the button will be rendered as part of document.body.

Example:

<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>

​

Use the React library

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

# 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 integrationId is not passed, it will display as [unknown app].

    To register your app with Pinecone and receive a unique integrationId, become a partner. Unregistered apps will have limited functionality and will appear as [unknown app] to the user.

• 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:

# Install dependencies
pip install pinecone-notebooks pinecone-client

# Connect to Pinecone and get an API key.
from pinecone_notebooks.colab import Authenticate

Authenticate()

# API key is available in the PINECONE_API_KEY environment variable.
import os

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

# Use the API key to set up the Pinecone client and create an index.
from pinecone import Pinecone, ServerlessSpec
import time

# Configure client
pc = Pinecone(api_key=api_key)

​

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.

   • API keys generated by the embeddable JavaScript script and React library are prepended with <integrationId>- (default: unknown-).
   • API keys generated by the Python library for Colab are prepended with colab-.

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.