How to Integrate Bolt.new with Asana

Asana personal access tokens provide full API access on behalf of your user account. To generate one, log into Asana and navigate to app.asana.com/0/developer-console. Click 'Create new token', give it a descriptive name like 'Bolt Integration', and copy the generated token immediately — Asana only shows it once. If you need to see it again, you must generate a new token. Unlike OAuth tokens that expire, personal access tokens persist until you manually revoke them. This makes them ideal for server-side applications that run continuously. The trade-off is that the token represents your personal identity — API actions will be attributed to your Asana account. For apps used by multiple team members, an OAuth flow is more appropriate, but for personal dashboards and automations, a personal token is simpler and sufficient. Asana uses standard Bearer token authentication. Every API request includes an Authorization header in the format 'Bearer {your-token}'. Store the token as ASANA_ACCESS_TOKEN in your .env.local file. Your workspace GID is the number in the Asana URL when viewing your workspace. Project GIDs follow the same pattern — the number in the URL when a project is open. You can discover your workspace GID programmatically by calling GET https://app.asana.com/api/1.0/workspaces with your token — this returns all workspaces your account has access to. Similarly, GET /projects in a workspace returns all visible projects. Both calls work from Bolt's WebContainer during development.

1// .env.local
2ASANA_ACCESS_TOKEN=your_personal_access_token
3ASANA_WORKSPACE_GID=your_workspace_gid
4ASANA_PROJECT_GID=your_default_project_gid

Asana's API uses a consistent pattern: most endpoints return an array of objects under a 'data' key, each containing at minimum a 'gid' and 'name'. Use the 'opt_fields' query parameter to request specific fields beyond the defaults — this dramatically reduces response size and API latency by avoiding the return of unused data. To fetch projects in a workspace, call GET /projects?workspace={workspaceGid}. To fetch tasks in a project, call GET /tasks?project={projectGid}. The tasks endpoint supports important filter parameters: completed_since ('now' returns only incomplete tasks), due_on.before, due_on.after, assignee, and modified_since for incremental updates. Task objects by default only return gid and name. Use opt_fields to request additional properties: completed, due_on, assignee.name, assignee.gid, memberships.section.name, memberships.project.name, notes, tags.name, custom_fields, and num_subtasks. The memberships field is particularly useful — it tells you which section within the project the task belongs to. Asana paginates results with a default limit of 20 items per page. Use the limit parameter (max 100) to increase this, and check the next_page.offset value in responses to fetch subsequent pages. For projects with hundreds of tasks, implement pagination to ensure you retrieve all tasks. All Asana API calls are outbound HTTP requests that work in Bolt's WebContainer without any deployment. Build your project dashboard in the Bolt preview and see live Asana data during development.

1// app/api/asana/tasks/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ASANA_API = 'https://app.asana.com/api/1.0';
5const ACCESS_TOKEN = process.env.ASANA_ACCESS_TOKEN;
6const DEFAULT_PROJECT_GID = process.env.ASANA_PROJECT_GID;
7
8type AsanaTask = {
9  gid: string;
10  name: string;
11  completed: boolean;
12  due_on: string | null;
13  assignee: { gid: string; name: string } | null;
14  memberships: Array<{ section: { name: string } }>;
15  notes: string;
16};
17
18async function asanaFetch(path: string, params: Record<string, string> = {}) {
19  const url = new URL(`${ASANA_API}${path}`);
20  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
21
22  const res = await fetch(url.toString(), {
23    headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
24  });
25
26  if (!res.ok) throw new Error(`Asana API ${res.status}: ${await res.text()}`);
27  return res.json();
28}
29
30export async function GET(request: NextRequest) {
31  const { searchParams } = new URL(request.url);
32  const projectGid = searchParams.get('project') ?? DEFAULT_PROJECT_GID;
33
34  const data = await asanaFetch('/tasks', {
35    project: projectGid!,
36    completed_since: 'now',
37    limit: '100',
38    opt_fields: 'gid,name,completed,due_on,assignee.name,assignee.gid,memberships.section.name,notes,tags.name',
39  });
40
41  const tasks: AsanaTask[] = data.data;
42
43  // Group tasks by section
44  const sections: Record<string, AsanaTask[]> = {};
45  for (const task of tasks) {
46    const sectionName = task.memberships?.[0]?.section?.name ?? 'No Section';
47    if (!sections[sectionName]) sections[sectionName] = [];
48    sections[sectionName].push(task);
49  }
50
51  return NextResponse.json({ sections, total: tasks.length });
52}

Creating a task in Asana requires a POST to /tasks with a 'data' wrapper object. Required fields vary: at minimum you need either 'projects' (an array of project GIDs to add the task to) or 'workspace' plus 'assignee'. Recommended fields for a useful task: name, notes (the task description, plain text), due_on (ISO 8601 date string like '2026-06-15'), assignee (user GID), projects (array of project GIDs), memberships (array of objects with project and section GIDs to place the task in a specific section), and tags (array of tag GIDs). Note the Asana API's request body format: all fields must be nested under a 'data' key: { data: { name: '...', projects: ['...'] } }. Omitting this wrapper results in a 400 error. Updating a task uses PUT /tasks/{taskGid} with the same 'data' wrapper, including only the fields you want to change. To mark a task complete, PUT /tasks/{taskGid} with { data: { completed: true } }. To add a comment (Asana calls them 'stories'), POST to /tasks/{taskGid}/stories with { data: { text: '...' } }. For custom fields — fields unique to your workspace configuration — you need the custom field GID and the appropriate value format. Retrieve custom field definitions from GET /projects/{projectGid} with opt_fields=custom_fields to see which custom fields exist and their GIDs and types. Task creation and updates are outbound HTTP calls that work in Bolt's WebContainer. You can create real Asana tasks from your Bolt development environment without deploying — a convenient way to verify your form integrations are working before going to production.

1// app/api/asana/tasks/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ASANA_API = 'https://app.asana.com/api/1.0';
5const ACCESS_TOKEN = process.env.ASANA_ACCESS_TOKEN;
6
7export async function POST(request: NextRequest) {
8  const { name, notes, project_gid, section_gid, assignee_gid, due_on } = await request.json();
9
10  if (!name || !project_gid) {
11    return NextResponse.json(
12      { error: 'name and project_gid are required' },
13      { status: 400 }
14    );
15  }
16
17  // Asana requires the 'data' wrapper in all request bodies
18  const taskData: Record<string, unknown> = {
19    name,
20    projects: [project_gid],
21  };
22
23  if (notes) taskData.notes = notes;
24  if (due_on) taskData.due_on = due_on;
25  if (assignee_gid) taskData.assignee = assignee_gid;
26  if (section_gid) {
27    taskData.memberships = [{ project: project_gid, section: section_gid }];
28  }
29
30  const response = await fetch(`${ASANA_API}/tasks`, {
31    method: 'POST',
32    headers: {
33      Authorization: `Bearer ${ACCESS_TOKEN}`,
34      'Content-Type': 'application/json',
35    },
36    body: JSON.stringify({ data: taskData }), // <-- Required 'data' wrapper
37  });
38
39  if (!response.ok) {
40    const error = await response.json();
41    return NextResponse.json({ error: error.errors }, { status: response.status });
42  }
43
44  const result = await response.json();
45  const task = result.data;
46  return NextResponse.json({
47    gid: task.gid,
48    name: task.name,
49    permalink_url: task.permalink_url,
50  });
51}

Asana webhooks allow your app to receive real-time push notifications when tasks are created, updated, or deleted — eliminating the need for polling and ensuring your dashboard reflects changes instantly. Asana webhooks use a two-step handshake: when you register a webhook, Asana sends a handshake request containing an X-Hook-Secret header, and your handler must echo back that secret in the response header. After a successful handshake, Asana sends events as POST requests. Before setting up webhooks, deploy your app to Netlify or Vercel. In Bolt, click the Publish button to deploy to Netlify. Your app gets a public URL like your-app.netlify.app. After deployment, add your environment variables (ASANA_ACCESS_TOKEN, ASANA_WORKSPACE_GID, ASANA_PROJECT_GID) in Netlify's Site Settings → Environment Variables. Redeploy after adding variables. Register the webhook by calling POST https://app.asana.com/api/1.0/webhooks with the data wrapper: { data: { resource: projectGid, target: 'https://your-app.netlify.app/api/asana/webhook', filters: [{ resource_type: 'task', action: 'changed' }] } }. Your webhook handler must respond to the initial handshake synchronously within 10 seconds. Each webhook event payload is an array of 'events' with resource (the changed object), resource_type, action, and change details. Multiple changes can be batched into a single webhook call. Process them efficiently and return 200 immediately. During development in Bolt's WebContainer, incoming webhooks cannot reach your app since it runs in the browser with no public URL. This is a fundamental constraint of WebContainers architecture — the browser sandbox cannot accept inbound TCP connections. Use polling (refetch every 30 seconds) as an alternative during development, and switch to webhooks after deployment.

1// app/api/asana/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function POST(request: NextRequest) {
5  // Step 1: Asana handshake — echo back the X-Hook-Secret header
6  const hookSecret = request.headers.get('x-hook-secret');
7  if (hookSecret) {
8    return new NextResponse(null, {
9      status: 200,
10      headers: { 'X-Hook-Secret': hookSecret },
11    });
12  }
13
14  // Step 2: Process regular webhook events
15  const payload = await request.json();
16  const events: Array<{
17    resource: { gid: string; name?: string };
18    resource_type: string;
19    action: string;
20    change?: { field: string; new_value: unknown };
21  }> = payload.events ?? [];
22
23  for (const event of events) {
24    console.log(`Asana event: ${event.resource_type} ${event.action}`, {
25      gid: event.resource.gid,
26      name: event.resource.name,
27      change: event.change,
28    });
29  }
30
31  return NextResponse.json({ received: events.length });
32}