Linear Connection

The Linear connection type enables automations to interact with Linear — the issue tracking and project management tool used by modern engineering teams. With this connection, workflows can create issues, update their state, assign team members, and query project backlogs without anyone needing to touch Linear manually.

Connection Details

Property	Value
Type ID	LINEAR
Category	Enterprise Applications — Issue Tracking
Testable	Yes

Friendly Example

What you enter	Example
Connection name	Linear - Product Backlog
Used for	Automatically filing bug reports from error-monitoring alerts and assigning them to the on-call engineer
Main details to collect	Linear API key and workspace ID
Best person to provide it	Linear workspace administrator or the engineer who owns the Linear account

After it is saved, workflow builders select Linear - Product Backlog in a node and the integration handles authentication transparently.

Mandatory Fields

Field	What It Means	Example
apiKey	Personal API key that authenticates all requests to the Linear GraphQL API. Encrypted at rest.	lin_api_xK9mNp3...
workspaceId	Unique identifier of the Linear workspace (organization) the automations should operate in	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Personal vs OAuth API Keys

Linear supports both personal API keys and OAuth application tokens. For automation use cases, personal API keys are simpler to set up. If your organization requires scoped permissions per application, contact your Linear workspace admin to create an OAuth application instead and use its access token here.

Advanced Fields

Linear's API is GraphQL-based and does not expose version or timeout parameters at the connection level. All advanced control (pagination, filtering, field selection) is handled in the individual workflow step configuration.

Setup Instructions

1. Log in to Linear at linear.app with the account you want to use for the integration. Using a shared service account is recommended so the key does not disappear if a team member leaves.

2. Navigate to API settings. Click your workspace avatar in the top-left corner, go to Settings, then select API from the left sidebar.

3. Create a personal API key. Under Personal API keys, click Create key. Enter a label (e.g., Qinfinite Automation) and click Create. Copy the key immediately — Linear shows it only once.

4. Find your Workspace ID. While still in Settings, select Workspace from the sidebar. The workspace ID appears in the page URL as settings/workspace — it is the UUID-format identifier in the URL path (e.g., https://linear.app/<workspace-slug>/settings/workspace). You can also find it by making a test GraphQL query to https://api.linear.app/graphql with query { viewer { organization { id } } } using your API key as a Bearer token.

5. Save the connection. Enter the API key and workspace ID in Global Configurator, then click Test Connection to verify that Linear responds correctly.

Use a Dedicated Service Account

If your team grows, a personal API key tied to an individual's account becomes a liability. Consider creating a dedicated Linear account (e.g., automation@yourorg.com), inviting it to the workspace, and using its API key for this connection.

Troubleshooting

Symptom	Likely Cause	Fix
401 Unauthorized or Authentication required	The API key is incorrect, revoked, or was copied with extra whitespace	Regenerate the API key in Linear Settings > API and update the connection
Entity not found when targeting a specific team or project	The team or project ID passed by the workflow step does not exist in this workspace	Verify the team and project IDs using the Linear API explorer or the Linear web UI URL
Workspace ID not accepted	The workspace ID was copied from the wrong place or formatted incorrectly	Use the GraphQL query in step 4 of Setup Instructions to retrieve the exact UUID programmatically
Rate limit errors during bulk operations	Linear enforces API rate limits per key	Add delays between bulk operations or switch to Linear's batch mutation endpoints