> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asana

> Connect Asana to Serval with a Personal Access Token so workflows can read and write tasks, projects, portfolios, and goals on demand.

## 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

| Capability                     | Description                                                                                                                                                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full Asana API access          | A single "Asana API request" action covers the entire Asana API surface - 192 typed operations generated from Asana's official specification - so workflows can read and write any Asana record from one connection. |
| Manage tasks                   | Read, create, update, and delete tasks, including assignees, due dates, custom fields, followers, and subtasks.                                                                                                      |
| Manage projects and portfolios | Work with projects, portfolios, portfolio items, custom field settings, and memberships.                                                                                                                             |
| Manage goals                   | Read and update goals, goal relationships, metrics, and followers.                                                                                                                                                   |
| Look up users and workspaces   | List and read users, workspaces, and workspace memberships.                                                                                                                                                          |
| Handle large lists             | Asana returns long lists one page at a time; workflows follow Asana's next-page marker to retrieve every item.                                                                                                       |

Anything defined in the [Asana API](https://developers.asana.com/reference/rest-api-reference) 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](https://developers.asana.com/docs/personal-access-token).

<Steps>
  <Step title="Open your Asana settings">
    In Asana, click your profile picture in the top right corner and select **Settings**.
  </Step>

  <Step title="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](https://app.asana.com/0/my-apps).
  </Step>

  <Step title="Create the token">
    Click **Create new token** and give it a descriptive name, such as "Serval Integration".
  </Step>

  <Step title="Copy the token immediately">
    Click **Create token** and copy the Personal Access Token right away.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<Tip>
  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.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the Asana connect form">
    In your team workspace, go to **Applications**, choose **Asana** from the catalog, and start a new connection. The **Configure Asana** dialog opens with two fields.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## 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.

<Tip>
  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.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Re-enter the API key whenever you edit the connection">
    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.
  </Accordion>

  <Accordion title="The token inherits its creator's Asana permissions">
    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.
  </Accordion>

  <Accordion title="Asana shows the token only once">
    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.
  </Accordion>

  <Accordion title="The credential only works against Asana's official API address">
    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.
  </Accordion>

  <Accordion title="Long lists arrive one page at a time">
    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.
  </Accordion>

  <Accordion title="Asana wraps every response in a data envelope">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Asana integration.