Skip to main content
What you can do:
  • Ingest Asana tasks into Gradial with full metadata
  • Filter by project, section, assignee, or tag
  • Trigger Gradial execution when tasks match your criteria
  • Write results — previews, links, comments — back to the Asana task

​
Prerequisites

​
Create a dedicated Gradial service account in Asana

Gradial requires a dedicated Asana user account — do not use a personal or shared account. This service account is what Gradial authenticates as when syncing tasks and posting results back to Asana.
  1. Create a new Asana user with an email address dedicated to the integration (e.g., [email protected])
  2. Add the service account as a member of every Asana project you plan to sync into Gradial
  3. Ensure the account has sufficient permissions to read tasks and post comments in those projects
The PAT you generate must come from this dedicated service account, not a personal user. Actions Gradial takes in Asana — such as posting comments — will appear as this account.
Required permissions for the service account:

​
Connect Asana to Gradial

Once the service account is set up, generate a PAT for it and connect to Gradial.

​
Step 1 — Generate a Personal Access Token

  1. Log in to Asana as the service account
  2. Go to the Asana Developer Console at app.asana.com/0/my-apps
  3. Click Create new token, give it a descriptive name (e.g., “Gradial Integration”), and confirm
  4. Copy the token immediately — it will not be shown again
Treat your PAT like a password. If it is ever compromised, revoke it from app.asana.com/0/my-apps and generate a new one.

​
Step 2 — Add the integration in Gradial

Go to Integrations in the Gradial sidebar, find Asana under Ticket System Integrations, and click Connect.
  1. Enter an Integration Name to identify this connection (e.g., “Marketing Asana”)
  2. Paste the token you generated into Personal Access Token
  3. Click Validate Connection
Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.

​
Configure routes

Once connected, click Add Route to define which Asana tasks Gradial ingests and where they go in Gradial. Each route has two parts: an Asana Filter that controls which tasks are fetched, and a Gradial Destination that controls where they land.

​
Asana Filter

Routes use GIDs — Asana’s internal numeric identifiers — not names. You can find GIDs in the URL when viewing a project, section, or workspace in Asana (e.g., app.asana.com/0/{workspace_gid}/{project_gid}).
Use Project GIDs to pull from one or more specific projects. Use Workspace GID + Assignee GID together to pull all tasks assigned to the Gradial service account across your workspace — regardless of project.
Use Test Query to preview which tasks the current filter will return before saving.

​
Gradial Destination

​
How task execution works

Once a route is configured, Gradial polls Asana for matching tasks and processes them automatically:
  1. A task matching a route’s filter criteria is discovered in Asana
  2. Gradial ingests the task as a thread, including title, description, and attachments
  3. The AI agent executes the requested work
  4. Results — previews, links, and comments — are written back to the original Asana task
  5. Gradial continues to monitor the task for updates or @gradial mentions that trigger follow-up actions

​
Troubleshooting

Contact your Gradial Product Specialist or email [email protected] if issues persist.