Skip to content

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

Sushmitha Malleshc83610a46443
diff --git a/docs/content/cookbooks/app-connections-dashboard.mdx b/docs/content/cookbooks/app-connections-dashboard.mdx
new file mode 100644
index 000000000..e549ece11
--- /dev/null
+++ b/docs/content/cookbooks/app-connections-dashboard.mdx
@@ -0,0 +1,105 @@
+---
+title: Build an App Connections Dashboard
+description: Build a dashboard for managing user app connections and auth status
+---
+
+[View source on GitHub](https://github.com/ComposioHQ/composio/tree/next/docs/examples/app-connections-dashboard)
+
+[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.
+
+## What you'll build
+
+- A connections dashboard showing all available apps and their auth status
+- Connect and disconnect buttons that handle OAuth flows
+
+## Prerequisites
+
+- [Bun](https://bun.sh) (or Node.js 18+)
+- [Composio API key](https://platform.composio.dev/settings)
+
+**Stack:** Next.js, `@composio/core`
+
+## Create the project
+
+```bash
+bunx create-next-app composio-dashboard --yes
+cd composio-dashboard
+bun add @composio/core
+```
+
+Add your API key to a `.env.local` file:
+
+```bash title=".env.local"
+COMPOSIO_API_KEY=your_composio_api_key
+```
+
+## Setting up the client
+
+Create `app/api/connections/route.ts`. Initialize the Composio client and set `dynamic = "force-dynamic"` so Next.js always fetches fresh connection data.
+
+<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#setup</include>
+
+## List connections
+
+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.
+
+<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#list</include>
+
+`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.
+
+<Callout>
+`session.toolkits()` paginates results. This example fetches up to 50. Use the `nextCursor` value from the response to fetch the next page.
+</Callout>
+
+## Connect an app
+
+The `POST` handler starts an OAuth flow for a given toolkit and returns the redirect URL.
+
+<include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#connect</include>
+
+`session.authorize(toolkit)` creates a connection request with a `callbackUrl`. After the user completes OAuth, they get redirected back to your app.
+
+## Disconnect an app
+
+Create `app/api/connections/disconnect/route.ts`. This endpoint takes a `connectedAccountId` and deletes it:
+
+<include meta='title="app/api/connections/disconnect/route.ts"'>../../examples/app-connections-dashboard/disconnect-route.ts</include>
+
+`composio.connectedAccounts.delete()` is a standalone SDK method. No session or provider needed.
+
+## Build the dashboard
+
+Replace `app/page.tsx` with a dashboard that shows connection cards:
+
+<include meta='title="app/page.tsx"'>../../examples/app-connections-dashboard/page.tsx</include>
+
+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.
+
+## Complete route
+
+The full `app/api/connections/route.ts` with both handlers:
+
+<include meta='title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts</include>
+
+## Running the app
+
+```bash
+bun dev
+```
+
+Open [localhost:3000](http://localhost:3000). You'll see all available apps with their connection status.
+
+1. Click **Connect** on GitHub. You'll be redirected to GitHub's OAuth page.
+2. Authorize the app. You'll land back on the dashboard with GitHub showing "Connected."
+3. Click **Disconnect** on GitHub. The connection is removed immediately.
+
+## Take it further
+
+<Cards>
+ <Card title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts">
+ Let users connect multiple accounts for the same toolkit
+ </Card>
+ <Card title="Connected accounts" href="/docs/auth-configuration/connected-accounts">
+ List, refresh, disable, and delete user connections
+ </Card>
+</Cards>
diff --git a/docs/content/cookbooks/chat-app.mdx b/docs/content/cookbooks/chat-app.mdx
index e0963289b..9787e04b0 100644
--- a/docs/content/cookbooks/chat-app.mdx
+++ b/docs/content/cookbooks/chat-app.mdx
@@ -112,14 +112,14 @@ Try a few more requests:
## Take it further
<Cards>
- <Card title="Configuring sessions" href="/docs/configuring-sessions">
- Lock down which toolkits your agent can access
+ <Card title="Build an App Connections Dashboard" href="/cookbooks/app-connections-dashboard">
+ A dedicated page where users manage their app connections
</Card>
- <Card title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
- Move authentication to your onboarding flow instead of in-chat
+ <Card title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts">
+ Let users connect multiple accounts for the same toolkit
</Card>
- <Card title="Users and sessions" href="/docs/users-and-sessions">
- Scope sessions to real users for multi-tenant apps
+ <Card title="Configuring sessions" href="/docs/configuring-sessions">
+ Lock down which toolkits your agent can access
</Card>
<Card title="How Composio works" href="/docs/how-composio-works">
Understand sessions, tool discovery, and execution under the hood
diff --git a/docs/content/cookbooks/index.mdx b/docs/content/cookbooks/index.mdx
index 07e9ddc93..b7939757e 100644
--- a/docs/content/cookbooks/index.mdx
+++ b/docs/content/cookbooks/index.mdx
@@ -13,6 +13,7 @@ Browse open-source templates or follow step-by-step guides below.
<Cards>
<Card title="Build a Chat App" href="/cookbooks/chat-app" description="Next.js chat app with tool discovery across 1000+ apps" />
+ <Card title="App Connections Dashboard" href="/cookbooks/app-connections-dashboard" description="Dashboard for managing user app connections" />
<Card title="Basic FastAPI Server" href="/cookbooks/fast-api" description="Build a Gmail agent with FastAPI" />
<Card title="Basic Hono Server" href="/cookbooks/hono" description="Build a Gmail agent with Hono.js" />
</Cards>
diff --git a/docs/content/cookbooks/meta.json b/docs/content/cookbooks/meta.json
index 671418793..6425c53b7 100644
--- a/docs/content/cookbooks/meta.json
+++ b/docs/content/cookbooks/meta.json
@@ -5,6 +5,7 @@
"---Getting Started---",
"templates",
"chat-app",
+ "app-connections-dashboard",
"fast-api",
"hono",
"---Productivity & Automation---",
diff --git a/docs/examples/app-connections-dashboard/connections-route.ts b/docs/examples/app-connections-dashboard/connections-route.ts
new file mode 100644
index 000000000..dfad6af5b
--- /dev/null
+++ b/docs/examples/app-connections-dashboard/connections-route.ts
@@ -0,0 +1,40 @@
+// region setup
+import { Composio } from "@composio/core";
+
+const composio = new Composio();
+
+export const dynamic = "force-dynamic";
+// endregion setup
+
+// region list
+export async function GET() {
+ const session = await composio.create("user_123");
+ const { items } = await session.toolkits({ limit: 50 });
+
+ return Response.json({
+ // Filter out toolkits that don't require authentication
+ toolkits: items
+ .filter((t) => !t.isNoAuth)
+ .map((t) => ({
+ slug: t.slug,
+ name: t.name,
+ logo: t.logo,
+ isConnected: t.connection?.isActive ?? false,
+ connectedAccountId: t.connection?.connectedAccount?.id,
+ })),
+ });
+}
+// endregion list
+
+// region connect
+export async function POST(req: Request) {
+ const { toolkit }: { toolkit: string } = await req.json();
+ const origin = new URL(req.url).origin;
+ const session = await composio.create("user_123");
+ const connectionRequest = await session.authorize(toolkit, {
+ callbackUrl: origin,
+ });
+
+ return Response.json({ redirectUrl: connectionRequest.redirectUrl });
+}
+// endregion connect
diff --git a/docs/examples/app-connections-dashboard/disconnect-route.ts b/docs/examples/app-connections-dashboard/disconnect-route.ts
new file mode 100644
index 000000000..e8b93b36d
--- /dev/null
+++ b/docs/examples/app-connections-dashboard/disconnect-route.ts
@@ -0,0 +1,10 @@
+import { Composio } from "@composio/core";
+
+const composio = new Composio();
+
+export async function POST(req: Request) {
+ const { connectedAccountId }: { connectedAccountId: string } =
+ await req.json();
+ await composio.connectedAccounts.delete(connectedAccountId);
+ return Response.json({ success: true });
+}
diff --git a/docs/examples/app-connections-dashboard/page.tsx b/docs/examples/app-connections-dashboard/page.tsx
new file mode 100644
index 000000000..9aef27b5f
--- /dev/null
+++ b/docs/examples/app-connections-dashboard/page.tsx
@@ -0,0 +1,92 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+type Toolkit = {
+ slug: string;
+ name: string;
+ logo?: string;
+ isConnected: boolean;
+ connectedAccountId?: string;
+};
+
+export default function Dashboard() {
+ const [toolkits, setToolkits] = useState<Toolkit[]>([]);
+ async function fetchConnections() {
+ const res = await fetch("/api/connections", { cache: "no-store" });
+ const data = await res.json();
+ setToolkits(data.toolkits);
+ }
+
+ useEffect(() => {
+ fetchConnections();
+ }, []);
+
+ async function connect(slug: string) {
+ const res = await fetch("/api/connections", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ toolkit: slug }),
+ });
+ const { redirectUrl } = await res.json();
+ window.location.href = redirectUrl;
+ }
+
+ async function disconnect(connectedAccountId: string) {
+ await fetch("/api/connections/disconnect", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ connectedAccountId }),
+ });
+ fetchConnections();
+ }
+
+ return (
+ <main className="max-w-4xl mx-auto p-6">
+ <h1 className="text-2xl font-bold mb-2">App Connections</h1>
+ <p className="text-gray-500 mb-6">
+ Connect your apps to give your agent access.
+ </p>
+
+ <div className="grid grid-cols-2 sm:grid-cols-3 gap-3">
+ {toolkits.map((t) => (
+ <div
+ key={t.slug}
+ className="flex items-center justify-between p-4 border rounded-lg"
+ >
+ <div className="flex items-center gap-3">
+ {t.logo && (
+ <img src={t.logo} alt={t.name} className="w-8 h-8 rounded" />
+ )}
+ <div>
+ <p className="font-medium">{t.name}</p>
+ <p
+ className={`text-xs ${
+ t.isConnected ? "text-green-600" : "text-gray-400"
+ }`}
+ >
+ {t.isConnected ? "Connected" : "Not connected"}
+ </p>
+ </div>
+ </div>
+ {t.isConnected ? (
+ <button
+ onClick={() => disconnect(t.connectedAccountId!)}
+ className="px-3 py-1.5 text-sm border rounded hover:bg-gray-50"
+ >
+ Disconnect
+ </button>
+ ) : (
+ <button
+ onClick={() => connect(t.slug)}
+ className="px-3 py-1.5 text-sm bg-black text-white rounded hover:bg-gray-800"
+ >
+ Connect
+ </button>
+ )}
+ </div>
+ ))}
+ </div>
+ </main>
+ );
+}