> 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-linear-integration.md).

# How to set up the Linear integration

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

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

#### In this guide

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

#### Set up the Linear 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.
* A Linear account with permission to create a Personal API key.
  {% endhint %}

Linear uses a single authentication method: a Personal API key minted from your Linear account. There is no separate Connect or OAuth flow.

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%2FKpiQR1ySAm6yZmatzlZy%2Fconfigure-linear-apikey.mp4?alt=media&token=fdb6ba3d-422d-4ae4-91cb-802546aaaced>" %}

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

Go to **Account Settings > Integrations** and click **Set up** next to **Linear**. The **Configure Linear** page opens with a single empty **Personal API key** field and a blue help block. The form's intro mentions an organization ID, but there is no organization-ID field to fill in; the Personal API key is all you need.

<figure><img src="/files/hKtcx4o6iNrdXery2lpf" alt="The Configure Linear page in Smaply. A Linear API Configuration form shows one empty required field labelled Personal API key, with a blue help block above listing two setup steps and a Save Configuration button below."><figcaption><p>Configure Linear, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create a Personal API key in Linear**

In a new tab, go to [linear.app/settings/account/security](https://linear.app/settings/account/security) and sign in. Under **Personal API keys**, click **Create new API key**, give it a name you'll recognise later (for example, `smaply-connector`), and click **Create**. Copy the generated key.
{% endstep %}

{% step %}
**Enter the key and save**

Back on the **Configure Linear** page, paste the key into the **Personal API key** field and click **Save Configuration**.
{% endstep %}

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

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

***

#### Verify the setup

Reopen the **Configure Linear** page from **Account Settings > Integrations**. A connected integration shows a masked **Personal API key**, with a green **Connection setup** message reading "Successfully connected to Linear as ...". Because the key is personal, the connection runs as the Linear user who created it.

<figure><img src="/files/wcJuF4p9IkemtCKue60I" alt="The Configure Linear page in Smaply showing a connected integration. A masked Personal API key is listed, with a green Connection setup callout confirming the account is connected to Linear, and Edit Configuration and Delete Configuration actions below."><figcaption><p>Connection established</p></figcaption></figure>

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

***

#### Use Linear in planning cards

Once Linear is connected, anyone in your workspace can add a planning card to a journey map, search Linear, and link the issue it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards.md).

***

#### Troubleshooting

The **Configure Linear** 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 key is wrong, incomplete, or was never copied in full. Reopen **Configure Linear**, click **Edit Configuration**, and paste the key again with no extra spaces. If it still fails, create a fresh Personal API key at [linear.app/settings/account/security](https://linear.app/settings/account/security) and enter the new one.

</details>

<details>

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

The connection works but Linear returns nothing for your search. Check that the search text matches an issue you can open in Linear, and that the key's owner has access to that team. The connection runs with that user's Linear permissions, so issues in teams they can't see won't appear.

</details>

<details>

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

A working Linear connection breaks if the Personal API key is deleted in Linear, or if the user who created it loses access to the relevant teams.

Create a new key at [linear.app/settings/account/security](https://linear.app/settings/account/security), then reopen **Configure Linear**, click **Edit Configuration**, and paste in the new key.

</details>

<details>

<summary><strong>Issues 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 Linear issues appear, the connection uses the key owner's Linear permissions. If a teammate can't find an issue you can see, the key owner may not have access to that team in Linear.

</details>

For questions about how the connection behaves across your account, such as disconnecting Linear 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 issues 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-linear-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.