> ## Documentation Index
> Fetch the complete documentation index at: https://docs.picaos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Setup
> Integrate AuthKit into your application in under 10 minutes
## Prerequisites
Before you begin, make sure you have:
* A [Pica account](https://app.picaos.com) (free to sign up)
* A Pica API key from your [API keys page](https://app.picaos.com/settings/api-keys)
* A web application where you want to add AuthKit
## Backend Setup
### Install the backend package
Install the AuthKit token generator for your backend. This package creates secure tokens that authorize users to connect integrations.
View on npm
```bash theme={null}
npm install @picahq/authkit-token
```
View on PyPI
```bash theme={null}
pip install authkit-token
```
### Set your Pica API key
Store your Pica API key as an environment variable. Never expose this key in your frontend code.
```bash theme={null}
PICA_SECRET_KEY=your_api_key_here
```
Get your API key from the [Pica dashboard](https://app.picaos.com/settings/api-keys).
### 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.
Create a file at `app/api/authkit/route.ts`:
```typescript theme={null}
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`:
```typescript theme={null}
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" });
}
}
```
```typescript theme={null}
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" });
}
});
```
```python theme={null}
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
```
```python theme={null}
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
A unique identifier for the user, team, organization, or project that will own the connection. Examples: `userId`, `teamId`, `organizationId`
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**.
### Install the frontend package
Install the AuthKit client library in your frontend application.
```bash theme={null}
npm install @picahq/authkit
```
View on npm
This package works with any major frontend framework.
### Add the AuthKit button
Create a button component that opens the AuthKit modal when clicked.
```typescript theme={null}
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 (
);
}
```
```vue theme={null}
```
```javascript theme={null}
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
URL of your backend endpoint that generates AuthKit tokens
Headers to include in the token request (e.g., authentication headers)
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.
Callback when a connection is successfully created. Receives the connection object as a parameter.
Callback when an error occurs. Receives the error object as a parameter.
Callback when the modal is closed (whether successful or not)
## Configure visible integrations
Navigate to the [AuthKit settings page](https://app.picaos.com/authkit) 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](/authkit/management).
## 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
Check out our example Next.js app with a full AuthKit implementation
## What's next?
Learn how to list, filter, and manage your users' connections
Use the Passthrough API to access your users' integration data
Email us at [support@picaos.com](mailto:support@picaos.com) for assistance
Navigate to the [AuthKit settings page](https://app.picaos.com/authkit) 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