Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxnew file mode 100644index 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.mdxindex 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 hooddiff --git a/docs/content/cookbooks/index.mdx b/docs/content/cookbooks/index.mdxindex 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.jsonindex 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.tsnew file mode 100644index 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 connectdiff --git a/docs/examples/app-connections-dashboard/disconnect-route.ts b/docs/examples/app-connections-dashboard/disconnect-route.tsnew file mode 100644index 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.tsxnew file mode 100644index 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>+ );+}