How to Integrate Mural with V0

Mural's API uses OAuth 2.0 for authentication. To get API access, you need to register a developer application in Mural's developer portal, which gives you a Client ID and Client Secret used to obtain access tokens. Go to developers.mural.co and sign in with your Mural account. Navigate to the Applications section and click Create Application. Give your app a name (e.g., 'V0 Dashboard Integration'), a brief description, and set the redirect URI to your Vercel deployment URL followed by /api/mural/callback — for example, https://your-project.vercel.app/api/mural/callback. This redirect URI is used during the OAuth authorization flow. After creating the application, Mural will show you the Client ID and Client Secret. Copy both immediately. For internal tools where you are the only user, you can streamline authentication by using Mural's client credentials flow or by manually obtaining a long-lived access token through the OAuth authorization code flow once and storing it as an environment variable. For the simplest setup for a single-tenant internal tool: complete the OAuth authorization flow once manually (using a tool like Postman or the Mural API Explorer), obtain an access token and refresh token, then store both in Vercel environment variables. Your API route uses the access token for requests and refreshes it using the refresh token when it expires. Mural access tokens typically expire after one hour. Note a key difference from simpler APIs: Mural does not offer static API keys for personal use the way tools like Calendly or OnceHub do. All access goes through OAuth, which adds complexity. For a V0 internal tool, the 'store a long-lived token' approach is the most practical path.

Add your Mural authentication credentials to Vercel so your API route can authenticate with the Mural API in production. Open Vercel Dashboard → your project → Settings → Environment Variables. Add the following variables: MURAL_ACCESS_TOKEN: The OAuth access token obtained from the authorization flow. This is a long string that grants API access. MURAL_REFRESH_TOKEN: The refresh token used to obtain a new access token when the current one expires. Access tokens expire after about one hour. MURAL_CLIENT_ID: Your Mural application's Client ID from the developer portal. MURAL_CLIENT_SECRET: Your Mural application's Client Secret. This is used to refresh the access token. MURAL_WORKSPACE_ID: The ID of your Mural workspace. Find this in your Mural workspace URL — when you are viewing your workspace at app.mural.co/t/workspacename, the workspace ID is the 'workspacename' slug or a numeric ID depending on how Mural formats it. Do not add NEXT_PUBLIC_ to any of these — all Mural credentials are sensitive and must remain server-side only. After saving, trigger a redeployment. For local development, add all variables to .env.local.

Use V0 to generate the front-end components for your Mural integration. Since Mural is a visual tool, the most impactful interfaces are gallery views with thumbnail images, searchable mural lists, and activity feeds showing recent workshop sessions. For a mural gallery, ask V0 to generate a responsive card grid where each card represents one mural. Cards should show the mural title, a thumbnail image (using the thumbnail URL returned by the API), last modified date, and an 'Open in Mural' link. V0 can generate polished card designs with hover effects, loading skeletons, and empty states. For a workspace overview dashboard, ask V0 to generate a sidebar showing rooms (Mural's organizational folders) and a main content area showing the murals within the selected room. This hierarchy mirrors how Mural organizes content — workspace → rooms → murals. For embedding a specific Mural interactively, V0 can generate an iframe component similar to the Miro or Figma embed pattern. The Mural embed URL follows the format https://app.mural.co/embed/MURAL_ID. Add 'use client' to the component since iframe embeds run client-side. One V0 limitation to be aware of: V0 generates the component structure correctly but cannot validate that mural IDs are real or that thumbnails will load. Test with real IDs from your Mural workspace after generating the UI.

Build the server-side API route that fetches mural data from the Mural REST API. Create app/api/mural/route.ts. This route authenticates with your stored access token and returns workspace and mural data to your V0 components. Mural's API base URL is https://app.mural.co/api/public/v1. The key endpoints for a gallery use case are: GET /workspaces/{workspaceId}/murals to list all murals in a workspace, and GET /workspaces/{workspaceId}/rooms to list rooms within the workspace. Each mural response includes an id, title, thumbnailUrl (for displaying preview images), createdOn and updatedOn timestamps, and the room it belongs to. The thumbnailUrl is a direct image URL you can use in an img tag or Next.js Image component. Access token refresh is a critical part of production-ready Mural integration. If the stored access token has expired (after ~1 hour), the API returns a 401 error. Your route should catch this and use the refresh token flow to get a new access token before retrying. The token refresh endpoint is POST https://app.mural.co/api/public/v1/authorization/oauth2/token with the refresh_token grant type. For the token refresh to work in production, your API route needs to update the stored access token somewhere accessible for future requests. Since Vercel environment variables cannot be updated at runtime, a practical approach is to store the current access token in an external key-value store (like Upstash Redis or Vercel KV) that your API route reads from and writes to. This allows seamless token refresh without manual Vercel dashboard intervention.

1import { NextRequest, NextResponse } from 'next/server';
2
3const MURAL_BASE_URL = 'https://app.mural.co/api/public/v1';
4
5async function muralFetch(path: string, accessToken: string) {
6  const response = await fetch(`${MURAL_BASE_URL}${path}`, {
7    headers: {
8      Authorization: `Bearer ${accessToken}`,
9      Accept: 'application/json',
10    },
11  });
12
13  if (response.status === 401) {
14    throw new Error('MURAL_TOKEN_EXPIRED');
15  }
16
17  if (!response.ok) {
18    throw new Error(`Mural API error: ${response.status} ${response.statusText}`);
19  }
20
21  return response.json();
22}
23
24async function refreshAccessToken(): Promise<string> {
25  const response = await fetch(
26    `${MURAL_BASE_URL}/authorization/oauth2/token`,
27    {
28      method: 'POST',
29      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
30      body: new URLSearchParams({
31        grant_type: 'refresh_token',
32        refresh_token: process.env.MURAL_REFRESH_TOKEN!,
33        client_id: process.env.MURAL_CLIENT_ID!,
34        client_secret: process.env.MURAL_CLIENT_SECRET!,
35      }),
36    }
37  );
38
39  if (!response.ok) {
40    throw new Error('Failed to refresh Mural access token');
41  }
42
43  const data = await response.json();
44  return data.access_token;
45}
46
47export async function GET(request: NextRequest) {
48  let accessToken = process.env.MURAL_ACCESS_TOKEN;
49  const workspaceId = process.env.MURAL_WORKSPACE_ID;
50
51  if (!accessToken || !workspaceId) {
52    return NextResponse.json(
53      { error: 'Mural environment variables are not configured' },
54      { status: 500 }
55    );
56  }
57
58  const { searchParams } = new URL(request.url);
59  const roomId = searchParams.get('room');
60
61  try {
62    let data;
63
64    try {
65      const endpoint = roomId
66        ? `/workspaces/${workspaceId}/rooms/${roomId}/murals`
67        : `/workspaces/${workspaceId}/murals`;
68      data = await muralFetch(endpoint, accessToken);
69    } catch (error: unknown) {
70      if (error instanceof Error && error.message === 'MURAL_TOKEN_EXPIRED') {
71        // Refresh and retry once
72        accessToken = await refreshAccessToken();
73        const endpoint = roomId
74          ? `/workspaces/${workspaceId}/rooms/${roomId}/murals`
75          : `/workspaces/${workspaceId}/murals`;
76        data = await muralFetch(endpoint, accessToken);
77      } else {
78        throw error;
79      }
80    }
81
82    const murals = (data.value || []).map((m: {
83      id: string;
84      title: string;
85      thumbnailUrl?: string;
86      createdOn: number;
87      updatedOn: number;
88      roomId?: string;
89    }) => ({
90      id: m.id,
91      title: m.title || 'Untitled Mural',
92      thumbnailUrl: m.thumbnailUrl || '',
93      createdOn: new Date(m.createdOn).toISOString(),
94      updatedOn: new Date(m.updatedOn).toISOString(),
95      roomId: m.roomId || '',
96      muralUrl: `https://app.mural.co/t/${workspaceId}/m/${m.id}`,
97    }));
98
99    return NextResponse.json({ murals, total: murals.length });
100  } catch (error: unknown) {
101    console.error('Mural API error:', error);
102    return NextResponse.json(
103      { error: 'Failed to fetch Mural data' },
104      { status: 500 }
105    );
106  }
107}