Asana Port

Purpose

This is the Harbor reference integration for the Asana API.

Use it when:

• building Asana actions in Harbor
• extending the Dock / Hub Asana entry
• teaching Codex or OpenClaw how to map a work-management API into Harbor Ports and Harbor Actions without turning Harbor into a generic project search proxy

Harbor Port worksheet

Product

• Product: Asana API
• Publisher slug: asana
• Publisher name: Asana
• Category: Work Management
• Tags: asana, tasks, projects, planning, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Asana API
• Description: Asana API connection managed locally through Harbor.
• Base URL: https://app.asana.com/api/1.0/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Asana fits Harbor well because:

• every starter action stays on one fixed origin
• project and task routes are explicit and reviewable
• Harbor can model the safe filters as typed query inputs
• task creation maps cleanly to a bounded JSON request body
• Harbor never needs to expose raw auth or arbitrary project-search transport

Good Harbor Asana starter actions:

• fixed GET reads for projects and tasks
• explicit POST writes for task creation
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• Asana's broader workspace search surfaces
• large mutation coverage beyond first-pass task creation
• generic forwarding across the whole Asana API
• broad admin or template operations before operator review

Starter Asana actions

Automatic read actions

• list-projects -> GET /projects
• list-tasks -> GET /tasks

Approval-friendly write actions

• create-task -> POST /tasks

Why these actions

These routes fit Harbor's current safe model well because they:

• cover the common operator loop of discovering projects, reviewing task lists, and creating a new task
• keep the route surface small and explicit
• use Harbor's Action Model for typed query values
• map cleanly to Asana's bearer-token auth model
• give Harbor an immediately useful work-management integration without taking on the bigger search and automation surfaces yet

Action Model notes

At execution time, callers should supply values by location:

• input.query for list-projects and list-tasks
• input.body for create-task

Example project listing request:

{
  "query": {
    "workspace": "1201234567890",
    "archived": false,
    "limit": 50
  }
}

Example task listing request:

{
  "query": {
    "project": "1201234567891",
    "completed_since": "now",
    "limit": 50
  }
}

Example task creation request:

{
  "body": {
    "data": {
      "name": "Review Harbor Asana port",
      "notes": "Validate the imported Asana starter actions",
      "projects": [
        "1201234567891"
      ],
      "workspace": "1201234567890"
    }
  }
}

For create-task, keep the JSON body bounded to the fields you actually intend to use, such as:

• data.name
• data.notes
• data.projects
• data.workspace
• data.assignee
• data.due_on
• data.due_at

Suggested operator workflow

1. Import the Asana Dock entry from Dock / Hub.
2. Configure the local Asana bearer token in Harbor Node.
3. Use list-projects to discover project and workspace IDs first.
4. Use list-tasks with explicit project or assignee filters to inspect current work.
5. Keep create-task on require_approval unless there is a clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Asana Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Asana routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Asana token
• widen Asana into a generic search proxy
• hide route names behind vague labels
• add broad mutation coverage without review

Current update strategy

For now, Asana updates are manual:

• update the Dock / Hub Asana integration document in apps/hub/catalog/integrations/asana/asana-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Scope notes

This starter set intentionally stays narrow.

That means:

• project and task reads use bounded query filters
• task creation is the only seeded write action
• search, comments, sections, and deeper workflow automation should be added later only when they remain fixed and reviewable

Official reference starting points

• Asana authentication: https://developers.asana.com/docs/authentication
• Asana quick start and base URL: https://developers.asana.com/docs/quick-start
• Get multiple projects: https://developers.asana.com/reference/getprojects
• Get multiple tasks: https://developers.asana.com/reference/gettasks
• Create a task: https://developers.asana.com/reference/createtask