Setup

Prerequisites

Before you begin, make sure you have:

A Pica account (free to sign up)
A Pica API key from your API keys page
A web application where you want to add AuthKit

Backend Setup

Step 1

Install the backend package

Install the AuthKit token generator for your backend. This package creates secure tokens that authorize users to connect integrations.

Node.js
Python

NPM Package

View on npm

npm install @picahq/authkit-token

PyPI Package

View on PyPI

pip install authkit-token

Step 2

Set your Pica API key

Store your Pica API key as an environment variable. Never expose this key in your frontend code.

PICA_SECRET_KEY=your_api_key_here

Get your API key from the Pica dashboard.

Step 3

Create a token generation endpoint

Create an API endpoint in your backend that generates AuthKit tokens. This endpoint should be called by your frontend when a user wants to connect an integration.

Next.js App Router
Next.js Pages Router
Express.js
FastAPI
Flask

Create a file at app/api/authkit/route.ts:

import { NextRequest, NextResponse } from "next/server";
import { AuthKitToken } from "@picahq/authkit-token";

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "POST, GET, PUT, DELETE, OPTIONS",
  "Access-Control-Allow-Headers": "Content-Type, Authorization",
};

export async function OPTIONS(req: NextRequest) {
  return NextResponse.json({}, { headers: corsHeaders });
}

export async function POST(req: NextRequest) {
  try {
    // Get the user's ID from your auth system
    // This is just an example - use your actual auth logic
    const userId = req.headers.get("x-user-id");
    
    if (!userId) {
      return NextResponse.json(
        { error: "Unauthorized" },
        { status: 401, headers: corsHeaders }
      );
    }

    const authKitToken = new AuthKitToken(process.env.PICA_SECRET_KEY!);
    
    const token = await authKitToken.create({
      identity: userId, // Your user's unique identifier
      identityType: "user" // user, team, organization, or project
    });

    return NextResponse.json(token, { headers: corsHeaders });
  } catch (error) {
    return NextResponse.json(
      { error: "Failed to generate token" },
      { status: 500, headers: corsHeaders }
    );
  }
}

Create a file at pages/api/authkit.ts:

import type { NextApiRequest, NextApiResponse } from "next";
import { AuthKitToken } from "@picahq/authkit-token";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  try {
    // Get the user's ID from your auth system
    const userId = req.headers["x-user-id"] as string;
    
    if (!userId) {
      return res.status(401).json({ error: "Unauthorized" });
    }

    const authKitToken = new AuthKitToken(process.env.PICA_SECRET_KEY!);
    
    const token = await authKitToken.create({
      identity: userId,
      identityType: "user"
    });

    res.status(200).json(token);
  } catch (error) {
    res.status(500).json({ error: "Failed to generate token" });
  }
}

import express from "express";
import { AuthKitToken } from "@picahq/authkit-token";

const app = express();
app.use(express.json());

app.post("/api/authkit", async (req, res) => {
  try {
    // Get the user's ID from your auth middleware
    const userId = req.user?.id;
    
    if (!userId) {
      return res.status(401).json({ error: "Unauthorized" });
    }

    const authKitToken = new AuthKitToken(process.env.PICA_SECRET_KEY!);
    
    const token = await authKitToken.create({
      identity: userId,
      identityType: "user"
    });

    res.json(token);
  } catch (error) {
    res.status(500).json({ error: "Failed to generate token" });
  }
});

from typing import Optional
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from authkit_token import AuthKitToken, IdentityType

app = FastAPI()

# Initialize the client with your API key
# In production, load this from environment variables
authkit_client = AuthKitToken("sk_live_your_api_key_here")

class TokenRequest(BaseModel):
    identity: Optional[str] = None
    identity_type: Optional[IdentityType] = None

@app.post("/authkit-token")
async def create_authkit_token(request: TokenRequest):
    # Create the token asynchronously
    token = await authkit_client.create_async(
        identity=request.identity,
        identity_type=request.identity_type
    )

    if token is None:
        raise HTTPException(
            status_code=500,
            detail="Failed to create token"
        )

    return token

from flask import Flask, jsonify, request
from authkit_token import AuthKitToken

app = Flask(__name__)

# Initialize the client with your API key
# In production, load this from environment variables
authkit_client = AuthKitToken("sk_live_your_api_key_here")

@app.route("/authkit-token", methods=["POST"])
def create_authkit_token():
    data = request.get_json() or {}
    
    identity = data.get("identity")
    identity_type = data.get("identity_type")

    # Create the token
    token = authkit_client.create(
        identity=identity,
        identity_type=identity_type
    )

    if token is None:
        return jsonify({"error": "Failed to create token"}), 500

    return jsonify(token)

Token parameters

identity

string

required

A unique identifier for the user, team, organization, or project that will own the connection. Examples: userId, teamId, organizationId

identityType

string

required

Specifies the type of entity that owns the connection. Must be one of: "user", "team", "organization", or "project"

Choose your identityType based on your use case:

user: Each user has their own personal connections
team: Team members share connections
organization: Company-wide shared connections
project: Project-specific isolated connections

Frontend Setup

Chrome Users: If you’re developing locally, you may need to disable Local Network Access Checks in Chrome flags. Navigate to chrome://flags, search for Local Network Access Checks, and set it to Disabled.

Step 1

Install the frontend package

Install the AuthKit client library in your frontend application.

npm install @picahq/authkit

NPM Package

View on npm

This package works with any major frontend framework.

Step 2

Add the AuthKit button

Create a button component that opens the AuthKit modal when clicked.

React
Vue
JavaScript

import { useAuthKit } from "@picahq/authkit";

export function ConnectIntegrationButton() {
  const { open, isLoading } = useAuthKit({
    token: {
      url: "/api/authkit", // Your token endpoint
      headers: {
        // Include any auth headers your endpoint needs
        "x-user-id": "user_123" // Example: pass user ID
      },
    },
    onSuccess: (connection) => {
      console.log("Successfully connected:", connection);
      // Handle successful connection (e.g., refresh your UI, save connection key)
    },
    onError: (error) => {
      console.error("Connection failed:", error);
      // Handle error (e.g., show error message to user)
    },
    onClose: () => {
      console.log("AuthKit modal closed");
    },
  });

  return (
    <button onClick={open} disabled={isLoading}>
      {isLoading ? "Loading..." : "Connect Integration"}
    </button>
  );
}

<template>
  <button @click="open" :disabled="isLoading">
    {{ isLoading ? 'Loading...' : 'Connect Integration' }}
  </button>
</template>

<script setup>
import { useAuthKit } from "@picahq/authkit";

const { open, isLoading } = useAuthKit({
  token: {
    url: "/api/authkit",
    headers: {
      "x-user-id": "user_123"
    },
  },
  onSuccess: (connection) => {
    console.log("Successfully connected:", connection);
  },
  onError: (error) => {
    console.error("Connection failed:", error);
  },
  onClose: () => {
    console.log("AuthKit modal closed");
  },
});
</script>

import { AuthKit } from "@picahq/authkit";

const authKit = new AuthKit({
  token: {
    url: "/api/authkit",
    headers: {
      "x-user-id": "user_123"
    },
  },
  onSuccess: (connection) => {
    console.log("Successfully connected:", connection);
  },
  onError: (error) => {
    console.error("Connection failed:", error);
  },
  onClose: () => {
    console.log("AuthKit modal closed");
  },
});

document.getElementById("connect-btn").addEventListener("click", () => {
  authKit.open();
});

Configuration options

token.url

string

required

URL of your backend endpoint that generates AuthKit tokens

token.headers

object

Headers to include in the token request (e.g., authentication headers)

selectedConnection

string

The name of a specific integration to open directly (e.g., “Google Sheets”, “Slack”). If provided, AuthKit will skip the integration list and open directly to that integration’s authentication flow.

onSuccess

function

Callback when a connection is successfully created. Receives the connection object as a parameter.

onError

function

Callback when an error occurs. Receives the error object as a parameter.

onClose

function

Callback when the modal is closed (whether successful or not)

Configure visible integrations

Navigate to the AuthKit settings page in your Pica dashboard to:

Toggle integrations: Enable or disable which integrations appear in your AuthKit modal
Set OAuth credentials: For OAuth integrations, provide your own Client ID and Client Secret to use your OAuth apps

By default, integrations are not visible. You can selectively enable only the integrations your users need. For more details on managing integrations and OAuth apps, see the Management guide.

Testing your integration

Once you’ve completed the setup, test the flow:

Click your “Connect Integration” button
The AuthKit modal should open with your enabled integrations
Select an integration and complete the authentication
Your onSuccess callback should receive the connection details

View complete demo

Check out our example Next.js app with a full AuthKit implementation

What’s next?

Manage connections

Learn how to list, filter, and manage your users’ connections

Make authenticated requests

Use the Passthrough API to access your users’ integration data

Get help

Email us at support@picaos.com for assistance

Get Started

AuthKit

ToolKit

MCP Server

SaaS Integrations

BuildKit

Prerequisites

Backend Setup

Install the backend package

NPM Package

PyPI Package

Set your Pica API key

Create a token generation endpoint

Token parameters

Frontend Setup

Install the frontend package

NPM Package

Add the AuthKit button

Configuration options

Configure visible integrations

Testing your integration

View complete demo

What’s next?

Manage connections

Make authenticated requests

Get help

Get Started

AuthKit

ToolKit

MCP Server

SaaS Integrations

BuildKit

Documentation Index

​Prerequisites

​Backend Setup

​Install the backend package

NPM Package

PyPI Package

​Set your Pica API key

​Create a token generation endpoint

​Token parameters

​Frontend Setup

​Install the frontend package

NPM Package

​Add the AuthKit button

​Configuration options

​Configure visible integrations

​Testing your integration

View complete demo

​What’s next?

Manage connections

Make authenticated requests

Get help

Prerequisites

Backend Setup

Install the backend package

Set your Pica API key

Create a token generation endpoint

Token parameters

Frontend Setup

Install the frontend package

Add the AuthKit button

Configuration options

Configure visible integrations

Testing your integration

What’s next?