> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-asana-integration.md).

# How to set up the Asana integration

An Admin connects Asana once at the account level. After that, anyone in your workspace can search Asana and link tasks to planning cards on any journey map.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Asana integration](#set-up-the-asana-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Asana in planning cards](#use-asana-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Asana integration

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* An Asana account you can sign in to and create a Personal access token from.
  {% endhint %}

Asana uses a single authentication method: a Personal access token, plus the Workspace ID of the Asana workspace you want to connect.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FAJYPjkyMAnqfx2Es1fm6%2Fasana_apikey_config.mp4?alt=media&token=1f0fb929-edec-4d69-84f4-1a8dc2261e74>" %}

{% stepper %}
{% step %}
**Open the Asana integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Asana**. The **Configure Asana** page opens with empty fields for your Workspace ID and Personal access token.

<figure><img src="/files/zzGpjU3gRw4yIQUKciTi" alt="The Configure Asana page in Smaply. An Asana API Configuration form shows two empty required fields labelled Workspace ID and Personal access token, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Asana, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a Personal access token in Asana and find your Workspace ID**

In a new tab, sign in to Asana at [app.asana.com](https://app.asana.com), then keep that tab open so the next two links return your data.

To get your token, open [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps). Under **Personal access tokens**, click **+ Create new token**. Enter a token name you'll recognise later, such as `smaply-connector`, tick **I agree to the Asana API Terms**, and click **Create token**.

<figure><img src="/files/Z5R6go8bk7L5KtwFk1e9" alt="The Asana developer console My apps page. The Personal access tokens section has a Create new token button, the Create new token dialog shows a token name and the Asana API Terms checkbox, and the Token details panel shows the generated token with a Copy button and a warning that it won&#x27;t be shown again."><figcaption><p>Asana developer console, creating a Personal access token</p></figcaption></figure>

To get your Workspace ID, open [app.asana.com/api/1.0/workspaces](https://app.asana.com/api/1.0/workspaces). The page returns a short list of your workspaces. Copy the `gid` value for the workspace you want to connect. That number is your Workspace ID.

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Asana shows the token only once. Click **Copy** and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Asana** page, paste the `gid` into **Workspace ID** and the token into **Personal access token**. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows a green confirmation. Asana is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Asana** page from **Account Settings > Integrations**. A connected integration shows your saved Workspace ID and a masked token, with a green **Connection setup** message confirming you're connected to your Asana workspace. From here you can also **Edit Configuration** or **Delete Configuration**.

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Asana in planning cards

Once Asana is connected, anyone in your workspace can add a planning card to a journey map, search Asana, and link the task it relates to. The card shows the task's live status and updates as it changes in Asana. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards.md).

***

#### Troubleshooting

The **Configure Asana** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The Workspace ID or token is wrong, or the token doesn't have access to that workspace. Reopen **Configure Asana**, click **Edit Configuration**, and check each value:

* **Workspace ID** is the `gid` from [app.asana.com/api/1.0/workspaces](https://app.asana.com/api/1.0/workspaces), with no extra characters. It's a number, not the workspace name.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Asana and re-enter both values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Asana returns nothing for your search. Check that the search text matches a task you can open in Asana, and that it lives in the workspace whose ID you connected. The connection runs with the token owner's Asana access, so tasks they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token revoked</summary>

A working Asana connection breaks if the token is deleted in Asana, or if the user who created it loses access to the workspace. Asana Personal access tokens act on behalf of the person who created them, so the connection depends on that account.

Create a new token at [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps), then reopen **Configure Asana**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Tasks are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Asana tasks appear, the connection uses the token owner's Asana access. If a teammate can't find a task you can see, the token owner may not have access to that project in Asana.

</details>

For questions about how the connection behaves across your account, such as disconnecting Asana or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link tasks from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-asana-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.