# Linear

Connect Linear and use its tools through the Authlane control plane.

## Prerequisites

Create a Linear OAuth application and choose a workspace containing the teams, issues, and projects
your SaaS will use. The authorizing user must be allowed to perform the requested changes. Use the
[developer documentation](https://linear.app/developers),
[OAuth guide](https://linear.app/developers/oauth-2-0-authentication), and
[API settings](https://linear.app/settings/api) during setup.

## Self-hosted setup

1. Open Linear **Settings → API → OAuth applications** and create an application.
2. Register `https://<your-authlane-host>/api/v1/oauth/linear/callback` as a callback URL.
3. Select the scopes below, save, and copy the generated Client ID and Client Secret.
4. Keep PKCE and refresh-token support enabled for user authorization.

## Configure authentication

Open **Dashboard → Services → Linear → OAuth Configuration**, enter the Client ID and Client Secret,
save, and enable Linear. Authlane always uses PKCE and stores the secret encrypted.

## Scopes

- `read` permits issue and project reads.
- `write` permits the exported issue and project mutations.

## Execution path

Prefer Linear's official MCP server at `https://mcp.linear.app/mcp`; the
[official MCP guide](https://linear.app/docs/mcp) confirms that existing Linear OAuth tokens can be
sent as bearer tokens. Use the direct GraphQL adapter only when the official server lacks a required
tool or is unavailable.

## Available tools

### Issues

- `linear_list_issues`
- `linear_create_issue`
- `linear_update_issue`

### Projects

- `linear_list_projects`
- `linear_create_project`

Install `@authlane/integration-linear` in the SaaS runtime. Each invocation gets a fresh lease and
the adapter calls Linear directly; Authlane serves connection state and definitions without
proxying tool inputs or results.

## Connection lifecycle

Successful Linear consent stores an encrypted credential and reports `connected`. If Linear
returns an expiring credential and refresh material, Authlane schedules background refresh.
Reconnect after a permanent refresh failure or an `expired` or `error` state. Disconnect through a
fresh hosted session after recent reauthentication.

## Troubleshooting

- Use team, issue, and project IDs returned for the connected workspace.
- A user can read an issue yet lack permission to update it; check workspace permissions and
  `write` consent together.
- Confirm required team and project references exist before creating issues or projects.