Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
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
+}