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.
Connect Asana to Mattering
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
Asana: List Tasks returns a 400 about filters
Asana: Search Tasks returns 402 Payment Required
Asana: Create Project fails with a team error
A response is missing fields that are visible in the Asana app
A pagination offset is rejected or a page sequence breaks
Nodes start failing with 429 Too Many Requests
Asana: Update Task will not change projects, tags, or followers
Related
The Asana MCP
What connecting Asana unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
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.