Menu

Mattering Automations Asana integration

Connect Asana to Mattering Automations: tasks, subtasks, projects, sections, tags, comments, followers, and URL attachments as workflow steps, authenticated with an Asana Personal Access Token.

The Mattering Automations Asana integration adds Asana to your automation canvas: create, update, complete, and organize tasks and subtasks, manage projects, sections, tags, followers, and comments, attach URLs, read custom field definitions, search a workspace, and turn names into gids with typeahead, all as workflow steps.

Setup takes a few minutes: create a Personal Access Token in Asana's developer console, attach it as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.

One design decision shapes everything downstream. Asana wraps every request body and every response in a data envelope, and the integration handles the two directions differently on purpose: on the way out, nodes add the wrapper automatically, so you configure plain fields and never type it; on the way back, responses are surfaced exactly as Asana sends them. That means a task's name lives at data.data.name in a node's output, list items at data.data[0], and the pagination token at data.next_page.offset, and it means captured outputs match Asana's own documentation line for line.

Before you start

  • An Asana account. The free Personal plan issues Personal Access Tokens and covers most of the surface; Asana: Search Tasks and meaningful custom field data require a paid Asana plan.
  • Access to Asana's developer console at app.asana.com/0/my-apps to create a Personal Access Token.
  • A Mattering workspace with access to the Automations app.
  • For organization features: teams only exist in Asana organizations, and creating a project in an organization requires a team gid. The is_organization field on Asana: Get Workspace tells you which kind you have.

Create an Asana Personal Access Token

Mattering authenticates to Asana with a Personal Access Token, sent as a Bearer credential on every request. A token acts as the user who created it, with that user's permissions: there are no scopes to choose and no documented expiry, though a token can be revoked from the developer console at any time.

Sign in to Asana and open the developer console at app.asana.com/0/my-apps.
Create a Personal access token and give it a name that says what it is for.
Copy the token and keep it somewhere safe until it is pasted into Mattering.
The token acts as you. Every task your automations create, comment on, or delete happens as your user with your permissions, and notifications go out under your name. For team automations, consider creating the token from a dedicated Asana user so workflow activity is clearly labeled and survives personnel changes.

Connect Asana to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Asana from the list.
Click Create new credential, paste your Personal Access Token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls Asana's get current user endpoint and confirms the token authenticates.
Click Connect. All 42 Asana nodes appear in your canvas palette.

Verify it works

After connecting, open any automation canvas and check the palette: an Asana section should list the query and action nodes. Drop Asana: Get My User onto the canvas and run a test step. It needs no configuration and is a safe, read-only call; a successful response shows your name, email, and workspaces under data.data, and a bad token returns a clean 401. Note the workspace gids it returns, because almost every other node wants one.

To confirm the rest of the surface, run Asana: List Workspaces and then Asana: List Projects with a workspace gid, or Asana: Typeahead Search to turn any object's name into its gid. Everything in the verify path is read-only. The only nodes that destroy anything are Asana: Delete Task and Asana: Delete Project, and neither appears anywhere in setup.

Node reference

42 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 22

Asana: Get Attachment

asana_get_attachment

Get one attachment's metadata, including download_url and view_url. download_url values are short-lived signed links; use them promptly rather than storing them.

Asana: Get My User

asana_get_me

Get the authenticated Asana user: gid, name, email, and the workspaces the token can reach. Needs no configuration, echoes no credential, and 401s on a bad token, so it doubles as the credential health check.

Asana: Get Project

asana_get_project

Get one project's full record.

Asana: Get Tag

asana_get_tag

Get one tag's full record.

Asana: Get Task

asana_get_task

Get one task's full record: name, notes, assignee, dates, completion, memberships (project + section), tags, followers, and custom field values.

Asana: Get Team

asana_get_team

Get one team's full record.

Asana: Get User

asana_get_user

Get one user's full record by gid, by email address, or with the string 'me' for the token owner.

Asana: Get Workspace

asana_get_workspace

Get one workspace or organization record. is_organization tells you whether teams exist here and whether project creation needs a team gid.

Asana: List Attachments

asana_list_attachments

List the attachments on a task (or project / project brief) as metadata records: name, host, and links. Never returns file bytes.

Asana: List Project Custom Field Settings

asana_list_project_custom_field_settings

List which custom fields are attached to a project (each setting wraps the field definition with its enum options). Premium feature, like all custom-field surfaces.

Asana: List Project Sections

asana_list_project_sections

List the sections (board columns / list headings) of a project, in order. Section gids feed the add-task-to-section and task-list nodes.

Asana: List Projects

asana_list_projects

List projects, filtered to a workspace and optionally by archived state. Compact records by default; the gids feed every project-scoped node.

Asana: List Subtasks

asana_list_subtasks

List a task's subtasks in order. Compact records by default.

Asana: List Task Stories

asana_list_task_stories

List a task's activity stories: comments (resource_subtype comment_added) plus system events like assignments and completions. Filter to comments downstream via resource_subtype.

Asana: List Tasks

asana_list_tasks

List tasks from one filter scope: a project, a section, OR an assignee combined with a workspace (Asana requires exactly one of those shapes). Compact records by default; use opt_fields for due dates, assignees, and completion state.

Asana: List Users

asana_list_users

List user records, filtered to a workspace or a team. Returns compact records (gid, name) by default; add opt_fields like email to enrich. The gids feed assignee and follower fields.

Asana: List Workspace Custom Fields

asana_list_workspace_custom_fields

List a workspace's custom field definitions, including enum options and their gids: exactly what you need to write custom_fields values on tasks. Custom fields are an Asana premium feature; free workspaces have little or nothing here.

Asana: List Workspace Tags

asana_list_workspace_tags

List the tags in a workspace. Tag gids feed the add/remove tag nodes and the task search tags.any filter.

Asana: List Workspace Teams

asana_list_workspace_teams

List the teams in a workspace that are visible to the token holder. Teams only exist in organizations (workspaces where is_organization is true); a plain workspace has none. Team gids are required to create projects in an organization.

Asana: List Workspaces

asana_list_workspaces

List the workspaces and organizations visible to the token. Almost every other Asana node wants a workspace gid from here.

Asana: Search Tasks

asana_search_tasks

Full-text and filtered task search across a workspace. An Asana PREMIUM feature: free workspaces get 402 Payment Required. Results are eventually consistent (new changes take 10 to 60 seconds to appear) and NOT paginated: there is no next_page; narrow with filters or sort plus date-range windows instead. Many more filter operators (custom fields, *.not, *.all, created_at ranges) work via extra_query.

Asana: Typeahead Search

asana_typeahead_search

Find objects in a workspace by (partial) name, the same matcher as Asana's own search box: the everyday way to turn a name into a gid without premium task search. One resource type per call; single page of results, no pagination.

Action nodes 20

Asana: Add Tag to Task

asana_add_tag_to_task

Add a tag to a task. Exact inverse: Remove Tag from Task. Returns an empty data record.

Asana: Add Task Followers

asana_add_task_followers

Add followers (collaborators) to a task so they get notifications. Exact inverse: Remove Task Followers. Returns the updated task.

Asana: Add Task to Project

asana_add_task_to_project

Add an existing task to a project (tasks can live in many projects), optionally into a specific section or position. Exact inverse: Remove Task from Project. Returns an empty data record.

Asana: Add Task to Section

asana_add_task_to_section

Move a task into a section (the task must already be in the section's project). This is how tasks move between board columns. Reversible by adding the task to another section. Returns an empty data record.

Asana: Attach URL to Task

asana_attach_url_to_task

Attach an external URL to a task (or project) as a named link attachment (resource_subtype external). This is the URL-only mode: no file bytes are uploaded, and third-party storage integrations (Dropbox, Google Drive) cannot be attached this way. Returns the new attachment record.

Asana: Comment on Task

asana_create_task_comment

Add a comment to a task (the API only allows comment stories to be created). Provide text OR html_text, not both. Returns the new story with resource_subtype comment_added.

Asana: Create Project

asana_create_project

Create a project in a workspace. In an organization (is_organization true) a team gid is REQUIRED; in a plain workspace it must be omitted. Returns the full new project.

Asana: Create Section

asana_create_section

Create a new section in a project, at the end by default or positioned with insert_before/insert_after. Returns the new section record.

Asana: Create Subtask

asana_create_subtask

Create a new subtask under a parent task. Returns the full new subtask record.

Asana: Create Tag

asana_create_tag

Create a tag in a workspace. Returns the full new tag record whose gid feeds Add Tag to Task.

Asana: Create Task

asana_create_task

Create a task. Asana requires at least ONE of projects, parent, or workspace so the task has a home. Returns the full new task including its gid and permalink_url.

Asana: Delete Project

asana_delete_project

PERMANENTLY delete a project. The API documents no recovery path; tasks that were only in this project lose that membership. Prefer Update Project with archived true, which is fully reversible. Returns an empty data record.

Asana: Delete Task

asana_delete_task

Delete a task. It moves to the deleting user's trash and is recoverable IN the Asana app for 30 days, then permanently removed; there is no API undelete, so treat this as destructive. Subtasks go with it. Returns an empty data record.

Asana: Remove Tag from Task

asana_remove_tag_from_task

Remove a tag from a task. The tag itself survives; re-adding restores the exact state. Returns an empty data record.

Asana: Remove Task Followers

asana_remove_task_followers

Remove followers from a task. Re-adding restores the exact state. Returns the updated task.

Asana: Remove Task from Project

asana_remove_task_from_project

Remove a task from one project. The task itself is untouched and keeps its other project memberships; re-adding restores membership. Returns an empty data record.

Asana: Set Task Parent

asana_set_task_parent

Make a task a subtask of another task (or move it between parents). To promote a subtask back to a top-level task, send extra_body {"parent": null}. Returns the updated task.

Asana: Update Project

asana_update_project

Update a project's fields; only the fields you set are changed. archived true/false is also the reversible archive/unarchive switch, the safe alternative to deletion. The team cannot be changed via the API.

Asana: Update Section

asana_update_section

Rename a section (name is currently the only field the API lets you update). Returns the updated section record.

Asana: Update Task

asana_update_task

Update a task's fields; only the fields you set change. completed true is how you mark a task complete (false reopens it). Projects, tags, and followers are NOT updatable here; use the dedicated add/remove nodes. Returns the updated task.

Using the integration

On the automation canvas

Asana nodes chain with every other node: a scheduled Asana: List Tasks sweep can mirror a project into Mattering Productivity for a two-way sync, a form submission can become a task in the right board column via Asana: Create Task and Asana: Add Task to Section, and Asana: Comment on Task can report workflow results where the team already reads them. Asana: Attach URL to Task links deliverables to tasks by URL; attachments in this integration are links and metadata reads, never file bytes, and Asana's API cannot create third-party storage attachments such as Dropbox or Google Drive.

From AI assistants over MCP

Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can list projects, read task state, and post comments through the same nodes your workflows use. The 22 query nodes are read-only, which makes them the safest Asana surface to hand an agent.

The data envelope and output paths

Requests are wrapped for you: nodes assemble the fields you configure and send them inside Asana's required data envelope, and extra_body objects merge into the inner body. Responses are not unwrapped: node output is the standard envelope of status_code, success, and data, where data is Asana's raw JSON, so single objects read data.data.field, list items data.data[0].field, and the pagination token data.next_page.offset. Unwrapping was rejected because it would discard next_page, hide Asana's errors array on failures, and make captured outputs diverge from Asana's own documentation.

Compact records and opt_fields

Asana returns compact records by default: gid, resource_type, and name. Every read node and every object-returning write node carries an opt_fields setting, a comma separated list of exactly the properties to return, with dotted paths into related objects such as assignee.name. This is the single most important field for making Asana outputs useful downstream: ask for the fields the workflow needs and they appear in the response. Each node's help text ships a sensible example list.

Pagination, search, and rate limits

List nodes take limit (1 to 100) and offset, where the offset token can only come from a previous response's data.next_page.offset and expires as data changes. Asana: Search Tasks differs on three counts: it is a paid Asana feature (free workspaces get a 402), results are eventually consistent (changes take 10 to 60 seconds to appear), and it returns no pagination at all, so narrow with filters and date windows instead of paging. Rate limits are per token: 150 requests per minute on free workspaces, 1,500 per minute on paid ones, search capped at 60 per minute, and 429 responses carry a Retry-After header. The nodes do not retry on their own; space schedules accordingly.

Deletes are real: archive instead

Asana: Delete Task sends the task and its subtasks to the deleting user's trash; it is recoverable inside the Asana app for 30 days and then permanently removed, and there is no API undelete, so treat it as destructive. Asana: Delete Project has no documented recovery path at all. The reversible alternative for projects is Asana: Update Project with archived set to true, which hides the project and can be undone at any time. Both delete nodes are flagged destructive so they stay deliberate steps, not defaults.

Troubleshooting

Test Connection fails with a 401
The token is invalid, was revoked in Asana's developer console, or picked up stray whitespace when pasted. Personal Access Tokens have no documented expiry, so a sudden 401 after months of working usually means the token was revoked or its creating user lost access. Create a fresh token in the developer console and update the credential on the connector.
Asana: List Tasks returns a 400 about filters
The API requires exactly one filter shape per call: a project, a section, or an assignee combined with a workspace. Anything else, including no filter at all or an assignee without a workspace, is rejected. Pick one scope; to cover several projects, run the node once per project, or use Asana: Search Tasks on a paid workspace.
Asana: Search Tasks returns 402 Payment Required
Task search is an Asana premium feature, so free workspaces cannot call it at any volume. On a free plan, Asana: Typeahead Search covers name lookups instantly, and Asana: List Tasks covers scoped reads by project, section, or assignee. Also remember search results are eventually consistent: changes take 10 to 60 seconds to appear even on paid plans.
Asana: Create Project fails with a team error
Whether a team gid is needed depends on the workspace type. In an organization (is_organization is true on Asana: Get Workspace) a team gid is required; in a plain workspace it must be omitted. Get team gids from Asana: List Workspace Teams. Note that a project's team cannot be changed through the API afterwards, so pick the right one at creation.
A response is missing fields that are visible in the Asana app
Asana returns compact records by default, usually just gid, resource_type, and name. Set the node's opt_fields to a comma separated list of the fields you need, using dotted paths for related objects (for example assignee.name, memberships.section.name, due_on, completed). The data is not gone; it simply was not requested.
A pagination offset is rejected or a page sequence breaks
Offset tokens are opaque, come only from a previous response's data.next_page.offset, and expire as the underlying data changes; they can never be built by hand or stored for later. Restart from the first page and follow tokens forward within the same run. If next_page is null, that was the last page. Asana: Search Tasks never returns next_page; narrow it with filters rather than trying to page.
Nodes start failing with 429 Too Many Requests
Asana allocates rate limits per token: 150 requests per minute on free workspaces, 1,500 per minute on paid ones, and search additionally capped at 60 per minute. The 429 response carries a Retry-After header and still consumes quota, and the nodes deliberately do not retry on their own. Space out schedules, page with larger limit values, and use opt_fields to get everything needed in fewer calls.
Asana: Update Task will not change projects, tags, or followers
That is the API's design, not a fault. Those surfaces move only through their dedicated nodes: Asana: Add Task to Project and Asana: Remove Task from Project for membership, Asana: Add Tag to Task and Asana: Remove Tag from Task for tags, Asana: Add Task Followers and Asana: Remove Task Followers for notifications. Marking a task complete is completed set to true on Asana: Update Task, and false reopens it.

Asana is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.

Start Free Explore our Products