Skip to main content

This demo walks you through integrating AuthKit into your application in under 5 minutes

​
Prerequisites

Before you begin, make sure you have:

​
Backend Setup

1

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.
npm install @picahq/authkit-node
2

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

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
Create a file at app/api/authkit/route.ts:
import { NextRequest, NextResponse } from "next/server";
import { AuthKitToken } from "@picahq/authkit-node";

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 }
    );
  }
}

​
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

1

Step 1

​
Install the frontend package

Install the AuthKit client library in your frontend application.
npm install @picahq/authkit
This package works with any major frontend framework.
2

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>
  );
}

​
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

AuthKit management page
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:
  1. Click your “Connect Integration” button
  2. The AuthKit modal should open with your enabled integrations
  3. Select an integration and complete the authentication
  4. 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
⌘I