Skip to main content

​
About Asana

Asana is a work management platform for tasks, projects, portfolios, and goals. Serval connects to Asana using an Asana Personal Access Token (PAT), which is stored as the connection’s API key and attached securely to every request Serval sends to Asana. The integration gives workflows on-demand access to the entire Asana API through a single, fully typed action, so Serval can look up or change any Asana record your token can reach. No workflows are pre-installed when you connect. Authentication: API key (Asana Personal Access Token). There is no OAuth flow and no Serval-requested scopes - the token carries exactly the Asana permissions of the user who created it. Data sync: On-demand only. There is no background sync, scheduled ingestion, or webhook listener - Serval talks to Asana only when a workflow runs an Asana action.

​
What the Asana integration enables

Anything defined in the Asana API can be accessed through Serval.

​
Get your credentials

Serval needs an Asana Personal Access Token. Create it as a user whose Asana permissions cover every workspace, project, and task your workflows need to reach - the token can see exactly what that user can see, nothing more. Asana’s official guide is here.
1

Open your Asana settings

In Asana, click your profile picture in the top right corner and select Settings.
2

Go to the developer console

Open the Apps tab, scroll to the Build new apps section, and click View developer console. You can also go directly to the Asana developer console.
3

Create the token

Click Create new token and give it a descriptive name, such as “Serval Integration”.
4

Copy the token immediately

Click Create token and copy the Personal Access Token right away.
Asana shows the token only once, at the moment of creation. If you navigate away without copying it, you will need to create a new token.
Because the token inherits its creator’s Asana permissions, create it as a user with access to everything your workflows will touch. If that user’s access changes later, recreate the token.

​
Connect in Serval

1

Open the Asana connect form

In your team workspace, go to Integrations, choose Asana from the catalog, and start a new connection. The Configure Asana dialog opens with two fields.
2

Enter an Instance Name (optional)

Instance Name is a human-readable label for this connection inside Serval. It does not affect which Asana workspace the token reaches. The same field appears again, pre-filled, on the connection’s settings page.
3

Paste your token into API Key

Paste the Asana Personal Access Token into the API Key field. It is a password-style field, so the value is hidden as you type. The form does not mark this field as required, but the connection cannot authenticate without it.
4

Save the connection

Click Submit. After saving, the API Key is displayed obfuscated - bullet dots with only the last 4 characters visible - and can be replaced later but never viewed in full.
There are no field-level validation messages on this form - a typo in the token will not be caught at save time. It will surface later as failed workflow runs, so paste carefully.
When editing an existing Asana connection - including simply renaming it - always re-enter the full Personal Access Token in the API Key field before saving. Do not clear pre-filled fields, and do not save while the API Key still shows only its masked value. When rotating tokens, paste the new token and save in one step.

​
Verifying the connection

Asana does not surface named health checks in Serval - the Health Checks section that appears on some integrations’ settings pages is not shown for Asana, and there is no built-in connection test with success or failure messages. The most direct way to confirm the connection works end to end is to run a quick read-only workflow against Asana - for example, one that looks up the users in your workspace - and check that it returns data. Your Serval team or Catalyst can set one up in a couple of minutes.
If a workflow fails or returns empty results even though the token was pasted correctly, the most common cause is permissions: the user who created the token cannot see the workspace, project, or task the workflow is targeting. Recreate the token as a user with access to that data, then replace it in the connection’s API Key field.

​
Gotchas and troubleshooting

When saving any change to an existing Asana connection - for example renaming it or rotating credentials - always re-enter the full Personal Access Token in the API Key field before submitting. Do not clear pre-filled fields, and do not save the form while the API Key shows only its masked placeholder. When rotating tokens, paste the new token and save in one step.
There are no scopes. If the user who created the token cannot see a workspace, project, or task, neither can Serval - requests are denied or come back empty. Create the token as a user with access to everything your workflows touch, and recreate it if that user’s access changes.
The Personal Access Token is displayed a single time at creation. If it is lost or revoked, create a new token in the Asana developer console and replace the connection’s API Key value.
Serval attaches your token only to requests going to Asana’s official API at app.asana.com. The Asana API request action already targets that address automatically, so this is handled for you - but requests to any other destination are never authenticated with this credential.
Asana does not return every item at once. Each response includes a next-page marker, and a workflow must pass that marker back on the following request, repeating until no marker remains. Workflows that skip this step only ever see the first page of results.
Asana nests both single records and lists inside a wrapper object named “data”, and by default returns compact records that include only a handful of fields. If a workflow gets a record back but key details are missing, it usually needs to request those fields explicitly via Asana’s optional-fields setting.
Need help? Contact support@serval.com for assistance with your Asana integration.