Management

Once AuthKit is set up, you’ll need to manage your users’ connections, configure which integrations are available, and make authenticated requests to access their data. This guide covers everything you need to know.

​

Understanding connection ownership

• Multi-tenant architecture: Each user, team, or organization has isolated connections
• Filtered queries: List connections for specific users or teams
• Access control: Users can only access connections they own
• Data isolation: No cross-contamination between users’ integration data

​

How identity scoping works

const token = await authKitToken.create({
  identity: "user_123", // The owner of future connections
  identityType: "user"  // The type of owner
});

• You can list all connections for user_123
• You can filter connections by this identity
• Requests made with these connection keys automatically scope to this user’s data

​

Managing connections

​

List connections for a user

curl 'https://api.picaos.com/v1/vault/connections?identity=user_123' \
  -H 'x-pica-secret: YOUR_API_KEY'

​

Delete a user’s connection

curl -X DELETE "https://api.picaos.com/v1/vault/connections/{CONNECTION_ID}" \
  -H "x-pica-secret: YOUR_API_KEY"

​

Add tags to a user’s connection

curl -X PATCH "https://api.picaos.com/v1/vault/connections/{CONNECTION_ID}" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["new-user", "default"]
  }'

​

Making authenticated requests

​

Using the Passthrough API

curl "https://api.picaos.com/v1/passthrough/users/me/profile" \
  -H "x-pica-secret: YOUR_API_KEY" \
  -H "x-pica-connection-key: {CONNECTION_KEY}" \
  -H "x-pica-action-id: conn_mod_def::F_JeCYGuzvg::yAM6bqGdRdm91ZbYejlbEA"

• x-pica-connection-key: The connection key from the user’s connected integration
• x-pica-action-id: The specific action you want to perform (found in the Available Actions API or in the Actions table in the Pica dashboard)
• The request is automatically authenticated using the stored credentials for that connection

​

Choosing the right connection key

1. List their connections to see what’s available
2. Filter by platform to find the specific integration you need
3. Use the connection key when making requests

​

Using ToolKit for Agents

import { Pica } from "@picahq/toolkit";
import { openai } from "@ai-sdk/openai";
import { stepCountIs, streamText } from "ai";

async function main() {
  const pica = new Pica(process.env.PICA_SECRET_KEY!, {
    identity: "user_123",
    identityType: "user",
    connectors: ["*"],
    actions: ["*"]
  });

  // Get connections for that identity
  const connections = await pica.getConnectedIntegrations();
  console.log("Connections:", connections);

  // Or, ask the AI to get the connections
  const systemPrompt = pica.systemPrompt;

  const { textStream } = streamText({
    model: openai("gpt-5"),
    tools: { ...pica.tools() },
    system: systemPrompt,
    prompt: "What connections do I have access to?",
    stopWhen: stepCountIs(10),
  });

  for await (const textPart of textStream) {
    process.stdout.write(textPart);
  }
}

main().catch(console.error);

​

Configuring integrations

​

Toggle integration visibility

Configure integrations visibility in the Pica dashboard

1. Navigate to the AuthKit settings page
2. Browse the list of integrations
3. Toggle integrations on or off based on what your application needs
4. Changes take effect immediately in your AuthKit modal

​

Set up OAuth applications

Configure OAuth credentials

1. Go to the AuthKit settings page
2. Select an OAuth integration (e.g., Gmail, Slack)
3. Click “Configure OAuth App”
4. Enter your Client ID and Client Secret from the integration’s developer console
5. Set the Redirect URI in your OAuth app to: https://api.picaos.com/connections/oauth/callback

Configure OAuth scopes and permissions

• Branding: Users see your app name during OAuth consent
• Rate limits: Higher API rate limits for your application
• Compliance: Meet enterprise security requirements
• Control: Full ownership of the OAuth relationship

​

Security best practices

// Good: Verify user is authenticated
const userId = await verifyUserSession(req);
if (!userId) {
  return res.status(401).json({ error: "Unauthorized" });
}

const token = await authKitToken.create({
  identity: userId,
  identityType: "user"
});

// Verify the connection belongs to the requesting user
const connection = await fetch(
  `https://api.picaos.com/v1/vault/connections/${CONNECTION_ID}`,
  { 
    headers: { "x-pica-secret": process.env.PICA_SECRET_KEY } 
  }
).then(r => r.json());

if (connection.identity !== userId) {
  return res.status(403).json({ error: "Forbidden" });
}

// Proceed with the request

​

Troubleshooting

​

What’s next?