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

# Linear

> Configure Linear connections in Genesis with either an API key or user OAuth so agents can work with issues, comments, teams, and projects.

## Overview

Linear appears in **Config -> Connections** under the **Dev Tools** category. Genesis supports two auth modes for Linear:

* `api_key` for a direct personal or service-style connection.
* `user_oauth` for user-authorized access through Linear OAuth.

After setup, Genesis tests the connection by querying the authenticated Linear `viewer` through `https://api.linear.app/graphql`.

For automatic issue pickup, continue to [Linear Automation (Auto-Pickup)](/docs/Setup/Linear-Automation). Automation requires a **shared** `api_key` connection.

## Setup workflow

<Steps>
  <Step title="Open the Linear connector">
    Go to **Config -> Connections**, choose **Dev Tools**, then select **Linear**.
  </Step>

  <Step title="Choose an auth mode">
    Use **API Key** if you want to paste a Linear personal API key directly. Use **User OAuth** if each user should connect their own Linear account.
  </Step>

  <Step title="Enter the connection details">
    For `api_key`, enter the required API key field. For `user_oauth`, create a Linear OAuth application in [Linear API Settings](https://linear.app/settings/api/applications), register the redirect URI shown by Genesis, then save the client credentials on the connection. Genesis pre-fills the fixed authorization and token URLs, defaults the scopes to `read` and `write`, and accepts either comma- or space-separated scope values. This OAuth flow is configured directly on the Linear connection, so you do not need a separate entry under **Config -> OAuth Providers** first.
  </Step>

  <Step title="Test and save">
    Run the built-in connection test, verify the authenticated Linear user, then save the connection. If you want tools to use it automatically, set it as your **My default** or a **Role default** for `linear`. On `linear_connector` calls you can also pass `connection` to target a specific saved connection.
  </Step>
</Steps>

<Note>
  If your deployment uses outbound allowlists or external access controls, allow Genesis to reach both `linear.app` and `api.linear.app` so the OAuth flow and GraphQL requests can succeed.
</Note>

<Note>
  The `api_key` mode is PAT-class. Roles need `access_pat_connections_tools` to
  save, update, or test that mode. `user_oauth` remains available without that
  permission.
</Note>

## Connection fields

### `api_key`

| **Field** | **Type** | **Required** | **Default** | **Notes** |
| - | - | - | - | - |
| **`api_key`** | String | Yes | none | Personal API key. Genesis shows the placeholder `lin_api_...`. Generate it from **Linear Settings -> API -> Personal API keys**. |

### `user_oauth`

Genesis preconfigures the provider-specific OAuth fields for Linear. In the connection flow, Genesis shows the redirect URI to register, fixes the provider URLs, and pre-populates the recommended scopes.

| **Field** | **Type** | **Required** | **Default** | **Notes** |
| - | - | - | - | - |
| **`client_id`** | String | Yes | none | Stored as **OAuth Client ID** on the connection. |
| **`client_secret`** | String | Yes | none | Stored as **OAuth Client Secret** on the connection. |
| **`authorization_url`** | String | No | `https://linear.app/oauth/authorize` | Fixed Linear authorization endpoint. |
| **`token_url`** | String | No | `https://api.linear.app/oauth/token` | Fixed Linear token endpoint. |
| **`scopes`** | String | No | `read`, `write` | Recommended and default scopes. Genesis accepts comma- or space-separated scopes, with `read write` shown as the recommended format in the setup flow. |

<Tip>
  The Connections UI suggests the OAuth connection name `linear_oauth_main`. Register the exact redirect URI shown in Genesis for that saved connection name.
</Tip>

## What it enables

After setup, Genesis can use `linear_connector_tools` to create, update, and search Linear issues, add comments, upload and download files, manage attachment links, and list available teams or projects. When `connection` is omitted on `linear_connector`, Genesis uses the effective default `linear` connection for the current user.

## Related pages

* [Connections](/docs/Setup/Connections)
* [Linear Automation (Auto-Pickup)](/docs/Setup/Linear-Automation)
* [Linear Connector Tools](/docs/Genbot-Toolkit/Linear-Connector-Tools)