> ## 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.
# Overview
> Learn how to add powerful third-party integrations to your SaaS application
Building a SaaS product that needs to integrate with third-party tools? Pica gives you everything you need to write integration logic quickly and reliably—without managing OAuth flows, API credentials, or dealing with each API's quirks.
## Why use Pica for integrations?
Your users connect their accounts through OAuth or API keys—you never need to store or manage credentials. Pica handles authentication, token refresh, and secure storage automatically.
Use the [Pica MCP Server](/sdk/mcp) in Cursor, Windsurf, or any MCP-compatible IDE. Pica's knowledge base writes integration requests for you, saving hours of reading through API documentation and figuring out schemas.
We never store or access your integration data. All API calls go directly from your app to the integration—Pica only handles authentication tokens. Your data is yours.
Need an integration we don't have? We can usually add it within a few days. New integrations are available immediately through the same API—no code changes required.
One API endpoint for 200+ integrations. No need to learn different authentication patterns, error handling, or rate limiting for each platform.
Our knowledge base covers rate limits, pagination, required fields, nested objects, and API quirks for every integration. Get reliable results without debugging each API's edge cases.
***
## What can you build?
With Pica, you can build integration features with **any of the 200+ integrations** available in our catalog—from CRMs like Salesforce and HubSpot, to communication tools like Gmail and Slack, to accounting platforms like QuickBooks and Stripe.
**Common integration patterns:**
* Sync data from customer CRMs, calendars, or project management tools into your app
* Automate emails, notifications, or updates across integrated platforms
* Pull reports and analytics from accounting, marketing, or sales tools
* Create records, update statuses, or trigger actions in third-party systems
* Build custom workflows that connect multiple tools together
Explore 200+ integrations and 25,000+ actions available
**Missing an integration you need?** Let us know and we can usually add it within a few days. Request integrations at [support@picaos.com](mailto:support@picaos.com).
## How it works
Pica provides two core components for building SaaS integrations:
### 1. AuthKit: Let users connect their accounts
[AuthKit](/authkit) is an embeddable UI component that lets your users securely connect their third-party accounts (Gmail, Slack, Salesforce, QuickBooks, etc.) directly in your app. Think of it as "Plaid for integrations."
AuthKit handles OAuth flows, token management, and secure credential storage so you never have to touch or store user credentials. When a user connects an integration, you get a `connectionKey` that you'll use to make authenticated requests on their behalf.
Complete setup guide for integrating AuthKit into your application
***
### 2. Passthrough API: Make authenticated requests
The [Passthrough API](/api-reference/passthrough) lets you make authenticated HTTP requests to any third-party API without managing credentials.
**What it does:**
* Provides a unified endpoint for 25,000+ actions across 200+ platforms
* Automatically authenticates requests using stored connection credentials
* Uses the same request/response schemas as the underlying API
* Handles rate limiting, retries, and error responses
* Returns data directly from the integration (no storage on Pica's side)
**Building requests:**
You can construct Passthrough API requests using:
1. The underlying API's documentation (same schemas apply)
2. The [Pica MCP Server](/sdk/mcp) which uses Pica's knowledge base to write requests for you—saving hours of reading through API docs
**Finding action IDs:**
Every integration action has a unique action ID. Find them in:
1. The [Pica dashboard tools page](https://app.picaos.com/tools)
2. The [Available Actions API](/api-reference/core/available-actions)
3. Using the [Pica MCP Server](/sdk/mcp) in your IDE
Learn how to construct requests and handle responses
***
## Complete integration workflow
Here's how all the pieces work together in a typical SaaS application.
**Two approaches for connections:**
* **Customer integrations** - Use [AuthKit](/authkit) to let your users connect their own accounts (recommended for multi-tenant apps)
* **Your integrations** - Connect integrations directly in the [Pica dashboard](https://app.picaos.com/connections) and use those for all users (simpler for single-account use cases)
### Customer-facing integrations
Let your users connect their own third-party accounts through your app.
User clicks "Connect Gmail" in your app → AuthKit modal opens → User authenticates → Connection created with a unique `connectionKey`
```typescript theme={null}
// Frontend: Open AuthKit
const { open } = useAuthKit({
token: { url: "/api/authkit" },
onSuccess: async (connection) => {
// Save connection to your database
await saveConnection(currentUser.id, connection);
}
});
```
Save the connection key to your database associated with the user. You'll use this key to make requests on their behalf.
```typescript theme={null}
// Backend: Save to database
await db.connections.create({
userId: currentUser.id,
platform: "gmail",
connectionKey: connection.connectionKey,
connectedAt: new Date()
});
```
Use the Passthrough API with the user's connection key to access their data or perform actions.
```typescript theme={null}
// Backend: Fetch user's Gmail emails
const userConnection = await db.connections.findOne({
userId: currentUser.id,
platform: "gmail"
});
const emails = await fetch(
"https://api.picaos.com/v1/passthrough/users/me/messages",
{
headers: {
"x-pica-secret": process.env.PICA_SECRET_KEY,
"x-pica-connection-key": userConnection.connectionKey,
"x-pica-action-id": "conn_mod_def::F_JeJ3qaLEg::v9ICSQZxR0un5_ketxbCAQ"
}
}
).then(r => r.json());
```
Process the data and display it in your app, sync it to your database, or use it in your workflows.
```typescript theme={null}
// Frontend: Display emails in your UI
return (
Your Emails
{emails.messages.map(email => (
))}
);
```
### Using your own integrations
If you don't need each user to connect their own accounts, you can connect integrations directly in the Pica dashboard and use those for all your users.
Go to the [Pica dashboard](https://app.picaos.com/connections) and connect the integrations you need (e.g., your company Gmail, Slack workspace, CRM account).
Copy the connection key from the dashboard and store it in your environment variables.
```bash .env theme={null}
PICA_SECRET_KEY=your_api_key
GMAIL_CONNECTION_KEY=your_gmail_connection_key
```
Use the Passthrough API with your connection key to access integration data.
```typescript theme={null}
// Backend: Use your own connection for all users
const emails = await fetch(
"https://api.picaos.com/v1/passthrough/users/me/messages",
{
headers: {
"x-pica-secret": process.env.PICA_SECRET_KEY,
"x-pica-connection-key": process.env.GMAIL_CONNECTION_KEY,
"x-pica-action-id": "conn_mod_def::F_JeJ3qaLEg::v9ICSQZxR0un5_ketxbCAQ"
}
}
).then(r => r.json());
```
Use the data in your application—all users will see data from your connected account.
***
## Managing integrations with the API
Use the [Core API](/api-reference/introduction) to programmatically manage integrations, connections, and actions in your application.
Complete API documentation for managing connectors, connections, and actions
***
## Development workflow tips
Use the [Pica MCP Server](/sdk/mcp) in Cursor, Windsurf, or any MCP-compatible IDE to:
* Explore available actions and their parameters
* Test API requests before writing code
* Get AI-powered suggestions for building integration requests
```json theme={null}
// Add to your IDE's MCP config
{
"mcpServers": {
"pica": {
"command": "npx",
"args": ["@picahq/mcp"],
"env": {
"PICA_SECRET": "your-api-key"
}
}
}
}
```
Test integration actions in the [Pica dashboard playground](https://app.picaos.com):
1. Connect your test account
2. Use the AI playground to test actions conversationally
3. Copy the working code to your application
Best practices for storing connection metadata:
* Save connection keys in your database encrypted at rest
* Associate connections with user IDs for multi-tenancy
* Store platform name, connection status, and created date
* Index by userId and platform for fast lookups
Connection errors can happen (expired tokens, revoked access, rate limits). Handle them gracefully:
```typescript theme={null}
try {
const data = await makePassthroughRequest(connectionKey);
return data;
} catch (error) {
if (error.status === 401) {
// Token expired - prompt user to reconnect
await notifyUserToReconnect(userId, platform);
} else if (error.status === 429) {
// Rate limited - retry with backoff
await retryWithBackoff(() => makePassthroughRequest(connectionKey));
} else {
// Other error - log and notify
console.error("Integration error:", error);
}
}
```
Track your integration usage in the [Pica dashboard](https://app.picaos.com):
* View API request logs and response times
* Monitor error rates by integration
* Set up alerts for authentication failures
* Track which integrations your users connect most
## Security best practices
Never expose your Pica API key in frontend code. API keys should only be used on your backend server.
* Store API keys in environment variables
* Never commit API keys to version control
* Rotate API keys periodically
* Use separate keys for development and production
Always verify that the requesting user owns the connection before making requests:
```typescript theme={null}
async function getUserEmails(requestingUserId: string, connectionId: string) {
// Verify the connection belongs to the requesting user
const connection = await db.connections.findOne({
id: connectionId,
userId: requestingUserId
});
if (!connection) {
throw new Error("Unauthorized: Connection not found");
}
// Now safe to use the connection
return await fetchEmails(connection.connectionKey);
}
```
Always serve your application over HTTPS in production to protect tokens and connection keys in transit.
Add rate limiting to your API endpoints to prevent abuse:
```typescript theme={null}
import rateLimit from 'express-rate-limit';
const limiter = rateLimit({
windowMs: 15 * 60 * 1000, // 15 minutes
max: 100 // limit each user to 100 requests per window
});
app.use('/api/integrations/', limiter);
```
Log and monitor integration usage for security audits:
```typescript theme={null}
async function logIntegrationUsage(userId: string, action: string, platform: string) {
await db.auditLog.create({
userId,
action,
platform,
timestamp: new Date(),
ipAddress: req.ip
});
}
```
***
## Next steps
Add user authentication to your app in under 10 minutes
Learn how to make authenticated integration requests
Explore 200+ integrations and 25,000+ actions
Step-by-step guides for common integration patterns
***
## Get help
Have questions? Email us at [support@picaos.com](mailto:support@picaos.com) for assistance