@devries-cameron20 / composio Mirror · read-only / commits / c83610a46
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 05:45 UTC

docs: add App Connections Dashboard cookbook

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Feb 25, 2026 at 20:16 UTC c83610a46443f8656a09e0742269be343f8303f1
7 files changed +255 -6
docs/content/cookbooks/app-connections-dashboard.mdx new
+105
@@ -0,0 +1,105 @@
1 +---
2 +title: Build an App Connections Dashboard
3 +description: Build a dashboard for managing user app connections and auth status
4 +---
5 +
6 +[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/app-connections-dashboard)
7 +
8 +[Build a Chat App](/cookbooks/chat-app) handles authentication in-chat. That works for getting started, but production apps need a dedicated page where users manage their connections. This cookbook builds a dashboard where users can see all available apps, connect via OAuth, and disconnect at any time.
9 +
10 +## What you'll build
11 +
12 +- A connections dashboard showing all available apps and their auth status
13 +- Connect and disconnect buttons that handle OAuth flows
14 +
15 +## Prerequisites
16 +
17 +- [Bun](https://bun.sh) (or Node.js 18+)
18 +- [Composio API key](https://platform.composio.dev/settings)
19 +
20 +**Stack:** Next.js, `@composio/core`
21 +
22 +## Create the project
23 +
24 +```bash
25 +bunx create-next-app composio-dashboard --yes
26 +cd composio-dashboard
27 +bun add @composio/core
28 +```
29 +
30 +Add your API key to a `.env.local` file:
31 +
32 +```bash title=".env.local"
33 +COMPOSIO_API_KEY=your_composio_api_key
34 +```
35 +
36 +## Setting up the client
37 +
38 +Create `app/api/connections/route.ts`. Initialize the Composio client and set `dynamic = "force-dynamic"` so Next.js always fetches fresh connection data.
39 +
40 +<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#setup</include>
41 +
42 +## List connections
43 +
44 +The `GET` handler creates a session and returns every toolkit's name, logo, and connection status. Toolkits where `isNoAuth` is `true` don't require authentication, so we filter them out.
45 +
46 +<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#list</include>
47 +
48 +`session.toolkits()` returns each toolkit with a `connection` object. When `connection.isActive` is `true`, the user has already authorized that app. We also return the `connectedAccountId` so the frontend can disconnect later.
49 +
50 +<Callout>
51 +`session.toolkits()` paginates results. This example fetches up to 50. Use the `nextCursor` value from the response to fetch the next page.
52 +</Callout>
53 +
54 +## Connect an app
55 +
56 +The `POST` handler starts an OAuth flow for a given toolkit and returns the redirect URL.
57 +
58 +<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#connect</include>
59 +
60 +`session.authorize(toolkit)` creates a connection request with a `callbackUrl`. After the user completes OAuth, they get redirected back to your app.
61 +
62 +## Disconnect an app
63 +
64 +Create `app/api/connections/disconnect/route.ts`. This endpoint takes a `connectedAccountId` and deletes it:
65 +
66 +<include meta='title="app/api/connections/disconnect/route.ts"'>../../examples/app-connections-dashboard/disconnect-route.ts</include>
67 +
68 +`composio.connectedAccounts.delete()` is a standalone SDK method. No session or provider needed.
69 +
70 +## Build the dashboard
71 +
72 +Replace `app/page.tsx` with a dashboard that shows connection cards:
73 +
74 +<include meta='title="app/page.tsx"'>../../examples/app-connections-dashboard/page.tsx</include>
75 +
76 +The page fetches toolkit connection status on load. Clicking **Connect** redirects the user to OAuth. After they authorize, the `callbackUrl` brings them back to the dashboard with the connection now active. Clicking **Disconnect** deletes the connection and refreshes the list.
77 +
78 +## Complete route
79 +
80 +The full `app/api/connections/route.ts` with both handlers:
81 +
82 +<include meta='title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts</include>
83 +
84 +## Running the app
85 +
86 +```bash
87 +bun dev
88 +```
89 +
90 +Open [localhost:3000](http://localhost:3000). You'll see all available apps with their connection status.
91 +
92 +1. Click **Connect** on GitHub. You'll be redirected to GitHub's OAuth page.
93 +2. Authorize the app. You'll land back on the dashboard with GitHub showing "Connected."
94 +3. Click **Disconnect** on GitHub. The connection is removed immediately.
95 +
96 +## Take it further
97 +
98 +<Cards>
99 + <Card title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts">
100 + Let users connect multiple accounts for the same toolkit
101 + </Card>
102 + <Card title="Connected accounts" href="/docs/auth-configuration/connected-accounts">
103 + List, refresh, disable, and delete user connections
104 + </Card>
105 +</Cards>
docs/content/cookbooks/chat-app.mdx
+6 -6
@@ -112,14 +112,14 @@ Try a few more requests:
112 ## Take it further
113
114 <Cards>
115 - <Card title="Configuring sessions" href="/docs/configuring-sessions">
116 - Lock down which toolkits your agent can access
115 + <Card title="Build an App Connections Dashboard" href="/cookbooks/app-connections-dashboard">
116 + A dedicated page where users manage their app connections
117 </Card>
118 - <Card title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
119 - Move authentication to your onboarding flow instead of in-chat
118 + <Card title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts">
119 + Let users connect multiple accounts for the same toolkit
120 </Card>
121 - <Card title="Users and sessions" href="/docs/users-and-sessions">
122 - Scope sessions to real users for multi-tenant apps
121 + <Card title="Configuring sessions" href="/docs/configuring-sessions">
122 + Lock down which toolkits your agent can access
123 </Card>
124 <Card title="How Composio works" href="/docs/how-composio-works">
125 Understand sessions, tool discovery, and execution under the hood
docs/content/cookbooks/index.mdx
+1
@@ -13,6 +13,7 @@ Browse open-source templates or follow step-by-step guides below.
13
14 <Cards>
15 <Card title="Build a Chat App" href="/cookbooks/chat-app" description="Next.js chat app with tool discovery across 1000+ apps" />
16 + <Card title="App Connections Dashboard" href="/cookbooks/app-connections-dashboard" description="Dashboard for managing user app connections" />
17 <Card title="Basic FastAPI Server" href="/cookbooks/fast-api" description="Build a Gmail agent with FastAPI" />
18 <Card title="Basic Hono Server" href="/cookbooks/hono" description="Build a Gmail agent with Hono.js" />
19 </Cards>
docs/content/cookbooks/meta.json
+1
@@ -5,6 +5,7 @@
5 "---Getting Started---",
6 "templates",
7 "chat-app",
8 + "app-connections-dashboard",
9 "fast-api",
10 "hono",
11 "---Productivity & Automation---",
docs/examples/app-connections-dashboard/connections-route.ts new
+40
@@ -0,0 +1,40 @@
1 +// region setup
2 +import { Composio } from "@composio/core";
3 +
4 +const composio = new Composio();
5 +
6 +export const dynamic = "force-dynamic";
7 +// endregion setup
8 +
9 +// region list
10 +export async function GET() {
11 + const session = await composio.create("user_123");
12 + const { items } = await session.toolkits({ limit: 50 });
13 +
14 + return Response.json({
15 + // Filter out toolkits that don't require authentication
16 + toolkits: items
17 + .filter((t) => !t.isNoAuth)
18 + .map((t) => ({
19 + slug: t.slug,
20 + name: t.name,
21 + logo: t.logo,
22 + isConnected: t.connection?.isActive ?? false,
23 + connectedAccountId: t.connection?.connectedAccount?.id,
24 + })),
25 + });
26 +}
27 +// endregion list
28 +
29 +// region connect
30 +export async function POST(req: Request) {
31 + const { toolkit }: { toolkit: string } = await req.json();
32 + const origin = new URL(req.url).origin;
33 + const session = await composio.create("user_123");
34 + const connectionRequest = await session.authorize(toolkit, {
35 + callbackUrl: origin,
36 + });
37 +
38 + return Response.json({ redirectUrl: connectionRequest.redirectUrl });
39 +}
40 +// endregion connect
docs/examples/app-connections-dashboard/disconnect-route.ts new
+10
@@ -0,0 +1,10 @@
1 +import { Composio } from "@composio/core";
2 +
3 +const composio = new Composio();
4 +
5 +export async function POST(req: Request) {
6 + const { connectedAccountId }: { connectedAccountId: string } =
7 + await req.json();
8 + await composio.connectedAccounts.delete(connectedAccountId);
9 + return Response.json({ success: true });
10 +}
docs/examples/app-connections-dashboard/page.tsx new
+92
@@ -0,0 +1,92 @@
1 +"use client";
2 +
3 +import { useEffect, useState } from "react";
4 +
5 +type Toolkit = {
6 + slug: string;
7 + name: string;
8 + logo?: string;
9 + isConnected: boolean;
10 + connectedAccountId?: string;
11 +};
12 +
13 +export default function Dashboard() {
14 + const [toolkits, setToolkits] = useState<Toolkit[]>([]);
15 + async function fetchConnections() {
16 + const res = await fetch("/api/connections", { cache: "no-store" });
17 + const data = await res.json();
18 + setToolkits(data.toolkits);
19 + }
20 +
21 + useEffect(() => {
22 + fetchConnections();
23 + }, []);
24 +
25 + async function connect(slug: string) {
26 + const res = await fetch("/api/connections", {
27 + method: "POST",
28 + headers: { "Content-Type": "application/json" },
29 + body: JSON.stringify({ toolkit: slug }),
30 + });
31 + const { redirectUrl } = await res.json();
32 + window.location.href = redirectUrl;
33 + }
34 +
35 + async function disconnect(connectedAccountId: string) {
36 + await fetch("/api/connections/disconnect", {
37 + method: "POST",
38 + headers: { "Content-Type": "application/json" },
39 + body: JSON.stringify({ connectedAccountId }),
40 + });
41 + fetchConnections();
42 + }
43 +
44 + return (
45 + <main className="max-w-4xl mx-auto p-6">
46 + <h1 className="text-2xl font-bold mb-2">App Connections</h1>
47 + <p className="text-gray-500 mb-6">
48 + Connect your apps to give your agent access.
49 + </p>
50 +
51 + <div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
52 + {toolkits.map((t) => (
53 + <div
54 + key={t.slug}
55 + className="flex items-center justify-between p-4 border rounded-lg"
56 + >
57 + <div className="flex items-center gap-3">
58 + {t.logo && (
59 + <img src={t.logo} alt={t.name} className="w-8 h-8 rounded" />
60 + )}
61 + <div>
62 + <p className="font-medium">{t.name}</p>
63 + <p
64 + className={`text-xs ${
65 + t.isConnected ? "text-green-600" : "text-gray-400"
66 + }`}
67 + >
68 + {t.isConnected ? "Connected" : "Not connected"}
69 + </p>
70 + </div>
71 + </div>
72 + {t.isConnected ? (
73 + <button
74 + onClick={() => disconnect(t.connectedAccountId!)}
75 + className="px-3 py-1.5 text-sm border rounded hover:bg-gray-50"
76 + >
77 + Disconnect
78 + </button>
79 + ) : (
80 + <button
81 + onClick={() => connect(t.slug)}
82 + className="px-3 py-1.5 text-sm bg-black text-white rounded hover:bg-gray-800"
83 + >
84 + Connect
85 + </button>
86 + )}
87 + </div>
88 + ))}
89 + </div>
90 + </main>
91 + );
92 +}