# Linear API Integration Guide: GraphQL, Webhooks, Auth (2026)

By Benjamin Torres · 2026-11-21 · Source: https://www.activepieces.com/blog/linear-api-integration-guide-graphql-webhooks-auth-2026

---
<aside class="tldr"><p class="tldr-label">Summary</p><p>Linear provides a single GraphQL endpoint for all data operations, requiring developers to manage query complexity, pagination, and authentication through Personal API Keys or OAuth2 applications.</p><ul><li>Linear enforces a 10,000-point complexity ceiling for all GraphQL API requests.</li><li>Webhook delivery failures trigger retries at intervals of 1 minute, 1 hour, and 6 hours.</li><li>The Free tier limits users to 250 active issues within the workspace.</li></ul></aside>

[Linear](https://linear.app/developers/pagination) provides a **single GraphQL endpoint** for all data operations. This requires you to define the exact shape of every response to avoid over-fetching.

While a legacy project management tool like Jira (a product by Atlassian) relies on hundreds of REST routes that provide predictable but rigid data structures, Linear consolidates its entire surface area into one entry point.

By consolidating these routes, Linear makes front-end updates efficient. It forces every integration (from a simple bash script to a complex workflow in [Activepieces](https://www.activepieces.com)) to handle the complexity of graph queries.

## Accessing the Linear API via GraphQL and OAuth2

### Generating Personal API Keys for internal scripts

To access the API for private scripts, you'll create a Personal API Key within the "API" tab of your Linear account settings. These keys grant the same level of access as the user who generated them.

![A computer screen showing the Linear account settings page, with a cursor hovering over a text field containing a long…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/d61926e3-0d72-4017-b925-5dbe6622126d/linear-api-integration-guide-graphql-webhooks-au-7fe4db43.webp)

Include the key in the `Authorization` header of every POST request once it is generated so the server recognizes the caller.

### Registering OAuth2 applications for third-party tools

For tools intended for use by multiple team members, you must register an OAuth2 application in the Linear workspace settings to obtain a Client ID and Client Secret. This flow is a secure handshake where users grant specific permissions without sharing their primary credentials.

Standard OAuth2 authorization code grant is the protocol Linear follows. This requires a pre-defined redirect URL to pass the temporary authorization code back to the integrating service.

### Setting Linear API OAuth scopes and permissions

Linear enforces security through scopes that define whether an application can read or write to specific resources like "issues," "comments," or "teams." By applying these granular labels during the authentication request, you ensure that a compromised token only exposes a subset of workspace data.

![Activepieces workflow builder showing a multi-step automation with an HTTP request step configuration panel open on the…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/a5180460-e385-4bee-8927-f2b3b0530b63/google-ads-api-access-levels-costs-and-setup-202-39596d54.webp)

At the query level, Linear enforces these scopes strictly. A request for "project" data fails immediately if the token only has "issue" access.

## Navigating the Linear GraphQL schema and core models

Linear organizes its data in a strict hierarchy where the Team acts as the root container for all operational workflows. This structure tethers every Issue to a specific team’s workflow and notification settings, which prevents orphaned tasks from cluttering the global workspace.

Understanding this ownership model is critical. You can't move an Issue between Teams without re-mapping its state and priority to the destination team's unique schema.

### Querying Issues and Projects with specific filters

A deeply nested `filter` object is what Linear’s `issues` and `projects` queries rely on to narrow results before they hit the execution engine.

By applying a `team: { id: { eq: "TEAM_ID" } }` filter, you limit the query to a specific department’s data.

Logical operators like `and` or `or` allow you to combine these filters to find specific subsets, such as issues that are both in a "Started" state and assigned to a specific user ID.

### Using Linear GraphQL mutations to update issues

Modifying data requires the `issueUpdate` or `projectUpdate` mutations, which accept a unique identifier and an input object containing the fields to change. When updating an issue's `stateId`, you must provide a UUID that exists within the team's workflow.

These mutations return the updated object in the response, allowing your application to refresh its local state immediately without making a second round-trip query to the server.

### Using the 'nodes' pattern for efficient data fetching

Linear implements the nodes pattern within its connection types to simplify the retrieval of list-based data. Instead of traversing the standard Relay-style `edges` and `node` wrapper for every item, you can request `nodes` directly to flatten the JSON response.

This reduces the depth of your GraphQL selection set. It lowers the computational cost of the query and makes the resulting data easier to map into frontend components or automation variables.

![Activepieces workflow builder showing a multi-step automation with the Send HTTP request step selected and its…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/9e36e973-de4a-435f-8912-12e666216b2d/self-host-mistral-ai-enterprise-deployment-guide-3f7fe28d.webp)

## Linear API pricing tiers and rate limit quotas

Linear is available across all its service levels, meaning you can start building without an immediate financial barrier.

### Linear API cost on Free and Paid plans

Linear bundles API access into the per-seat subscription price rather than billing it as a standalone usage fee.

| Plan | API Access | Issue Limit | Key Feature |
| :--- | :--- | :--- | :--- |
| Free | Included | 250 active | Personal API Keys |
| Standard | Included | Unlimited | OAuth2 Support |
| Plus | Included | Unlimited | Service Accounts |

![A close-up of a printed table showing three rows for Free, Standard, and Plus plans, with a column specifically…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/72ba0db8-97d6-4e4f-a29c-c526563231c4/linear-api-integration-guide-graphql-webhooks-au-ac06b367.webp)

Small teams can prototype integrations before committing to a budget because the Free tier includes API access at no cost. The Plus tier has the Service Accounts feature. This allows for bot-specific API keys instead of tying an integration to a personal user account.

### How Linear's query complexity rate limits work

Rather than a simple request count, Linear calculates rate limits based on query complexity. Linear assigns every GraphQL request a point value based on the number of objects and fields requested.

![Activepieces workflow builder with the Send HTTP request step selected, showing its configuration panel with HTTP method…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/58352882-31ce-42ab-9b0f-c4a0fe866a5c/deepseek-r1-vs-v3-for-business-ai-2026-guide-scr-ae99964b.webp)

| Query Scenario | Complexity Impact |
| :--- | :--- |
| Simple Issue fetch | Low point consumption |
| Issue with all Comments | Medium point consumption |
| Team with all Projects and Issues | Maximum point consumption (reaches 10,000 limit) |

Because the most complex queries hit the **10,000-point ceiling** immediately, you must implement pagination to break large data syncs into smaller chunks. Failing to stay within the rate limit results in a `**429 Too Many Requests**` error, until the hour-long bucket resets.

### Reading Linear API rate limit response headers

To avoid hitting hard limits, your application must inspect the metadata Linear returns with every API response. These headers provide a real-time countdown of your remaining capacity so your code can pause or slow down before a lockout occurs.

The total points allowed in a window is defined by `X-RateLimit-Complexity-Limit`, which sets your maximum burst capacity. The `X-RateLimit-Complexity-Remaining` header shows the points left in your current bucket, telling your script exactly how much more data it can request right now.

The Unix timestamp for the next refresh is found in the `X-RateLimit-Complexity-Reset` header, allowing your worker to sleep until the exact millisecond more points become available.

## Handling common Linear API errors and production limits

Linear API errors typically stem from strict validation of security tokens or the structural weight of the GraphQL request itself.

### Fixing Linear API 401 unauthorized errors

A 401 Unauthorized error indicates that the Personal Access Token or OAuth2 bearer token has either expired or lacks the necessary permissions for the requested resource.

By calling the viewer query, you can verify active permissions and token validity. This returns the authenticated user’s details and confirms the connection is live.

### Managing GraphQL complexity errors in nested queries

Linear prevents overly expensive queries by assigning a complexity score to every query, returning a 429 response with a RATELIMITED error if the total exceeds the per-request limit.

To lower the score, you must reduce the number of requested fields or use the first and last arguments to paginate through smaller batches of records. Monitoring the extensions field in the API response allows you to see the exact cost of the current query.

<blockquote class="pull"><p>Linear prevents overly expensive queries by assigning a complexity score to every query, returning a 429 response with a RATELIMITED error if the total exceeds the per-request limit.</p></blockquote>

### Handling Linear API 429 errors with backoff

When the API returns a 429 Too Many Requests status, the application must immediately halt outgoing traffic to avoid extended cooldown penalties. This response includes a Retry-After header that specifies the exact duration you must wait before attempting another request.

![Flow builder showing data reference syntax {{step_2'output'}} in Find Rows step configuration.](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/0c1fc024-0fe2-4ff7-bb18-f8061292a7de/copy-ai-pricing-2026-plans-costs-and-limits-scre-f3c7c43d.webp)

You should implement exponential backoff, where the delay between retries increases after each successive failure. This prevents a thundering herd effect where multiple workers simultaneously hammer the API the moment the rate limit window resets.

The screenshot of the workflow builder illustrates how to handle these data dependencies visually. It shows a "Find Rows" step highlighted to demonstrate how data references are passed between discrete tasks.

Utilizing these pre-built logic blocks allows teams to bypass the manual construction of retry loops and header parsing.

## Building real-time listeners with Linear webhooks

Linear webhooks enable your infrastructure to react instantly to workspace changes by pushing JSON payloads to a public URL whenever an issue is created, updated, or deleted.

### Setting up Linear webhook URLs per team

You define webhook subscriptions within the Linear Team Settings to ensure your listener only receives data relevant to specific workflows.

After navigating to the Webhooks tab, you must provide a destination URL and select from a list of granular triggers, such as "Issues," "Projects," or "Cycles." Scoping these events at the team level prevents your endpoint from being overwhelmed by organization-wide noise.

![A web browser showing a Webhooks tab with a list of checkboxes next to the words Issues, Projects, and Cycles.](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/421acbc2-a90c-4258-8e2b-d172d564fb01/linear-api-integration-guide-graphql-webhooks-au-c6575966.webp)

### Verifying the Linear-Signature header for security

For Linear webhooks, authenticating incoming requests via the Linear-Signature header is the only way to confirm that a payload originated from Linear rather than a malicious actor.

When you create a webhook, Linear provides a signing secret that you must use to calculate an HMAC SHA256 hash of the raw request body.

By comparing your local hash to the value provided in the header, you ensure the data hasn't been tampered with in transit.

### Troubleshooting Linear webhook delivery failures

Linear enforces a strict response window that requires your endpoint to acknowledge receipt before the connection is severed. If your server fails to return a 200-level status code within the timeout limit, Linear assumes a delivery failure and initiates a backoff schedule to attempt redelivery.

| Platform | Webhook Timeout | Retry Intervals |
| :--- | :--- | :--- |
| Linear | 5 seconds | 1 minute, 1 hour, 6 hours |
| GitHub | 10 seconds | No automatic redelivery |
| Slack | 3 seconds | Immediate (3 attempts) |

The five-second limit means you must offload heavy processing to a background task runner. Failure to decouple the ingestion from the processing results in a timeout.

## Scaling Linear workflows without custom infrastructure

Building on an abstraction layer removes the need to maintain a persistent server just to catch a webhook or map a JSON payload to a GraphQL mutation.

> **A robust automation platform provides this production-ready environment for teams who need to bypass the overhead of managing OAuth tokens and webhook listeners manually. If a specific connector is missing from the 750 integrations in the open-source monorepo, you can generate it with AI and add it privately to your instance without waiting for a vendor release. Roughly 60% of integrations are community-contributed, meaning the catalogue expands based on actual user needs rather than a closed vendor roadmap.**

### Using the Linear connector for zero-code mutations

The Linear connector eliminates the need to construct complex GraphQL mutations by providing a visual interface for issue and project management. Instead of manually defining input objects for the issueCreate mutation, you map data directly into fields for titles, descriptions, and team assignments.

### Automating issue syncs across Jira or GitHub

Bridging Linear with other project management tools requires a translator that understands different ID formats and state machines.

Jira (a project tracking tool for enterprise teams) uses a different status hierarchy than Linear, requiring a logic step to map "In Progress" to "Started."

GitHub (a developer platform for version control) triggers workflows based on pull request events that must be linked to specific Linear issue keys.

Slack (a team communication platform) is the destination for real-time alerts when high-priority issues are blocked.

The following canvas demonstrates a typical notification workflow where a Stripe payment failure triggers an immediate alert in a Slack channel.

574ms is all it took for the data to reach its destination without custom retry logic, as shown in this visual confirmation. Once these notifications are active, you can scale to more complex synchronization tasks.

Modern workflow engines handle these promotions through Git Sync and Release Management, moving flows from test environments to production as versioned software rather than private in-app saves.

This deliberate promotion step is why MoneyGram and FundingSocieties run the platform in production to manage their automation environments. You can verify these capabilities in the technical documentation for Release Management, which applies the same logic to both self-hosted and cloud instances.

### Centralizing webhook management for incoming signals

Centralizing webhook management replaces the brittle process of hardcoding secret keys into environment variables across multiple microservices. The dashboard is a single location to monitor the health of incoming signals from Linear, allowing you to rotate signing secrets or update endpoint URLs without redeploying code.

## The production checklist for Linear integrations

Hardening a Linear integration requires moving beyond simple query execution to a defensive posture that accounts for network instability and strict security protocols.

**These specific implementation details ensure that your middleware can survive the high-volume traffic of a growing engineering team without dropping issue updates or exposing sensitive workspace data.**

1. Implement Linear-Signature verification to ensure incoming webhooks originate from Linear’s servers rather than a malicious actor. 
2. Set a 5s timeout on all requests so that a hanging connection doesn't exhaust your server’s thread pool during a Linear service degradation. 
3. Log X-RateLimit headers to provide visibility into how close your application is to hitting the complexity-based throttling thresholds. 
4. Use @linear/sdk v91.0.0+ to gain access to the latest TypeScript definitions, which prevents runtime errors caused by missing schema fields. 
5. Paginate results at 50 per page to maintain low memory overhead and stay within the maximum allowed node limit per request.

### Rotate API keys every 90 days

Regularly generating new Personal Access Tokens or OAuth credentials prevents a leaked key from granting indefinite access to your workspace’s roadmap and private issue comments. Linear provides a dedicated API settings page for key management.

### Log GraphQL request IDs for debugging support

Every response from the Linear API includes a unique identifier in the header. This is the only way for their engineering team to trace a specific failed transaction in their backend logs.

By capturing this ID alongside your internal error logs, you provide the necessary evidence for support tickets when a mutation returns an unexpected internal server error.

### Validating input for Linear GraphQL mutations

Passing raw strings from external forms directly into a GraphQL mutation exposes your integration to injection attacks or malformed payload errors that can crash your sync engine.

You must validate that issue titles and descriptions conform to UTF-8 standards and strip any control characters that might violate the schema constraints.

## What Activepieces does about this

Activepieces provides a production-ready abstraction layer that handles the brittle complexities of Linear’s GraphQL schema and rate limiting automatically. Instead of writing custom logic to parse `X-RateLimit` headers or implement exponential backoff, you use the Linear integration to manage these constraints at the engine level.

The platform is open-source under the MIT license, allowing teams to inspect the underlying TypeScript code that flattens Linear’s nested nodes into usable data structures without manual mapping.

The platform solves the "thundering herd" problem by decoupling webhook ingestion from execution. When a Linear webhook hits your endpoint, Activepieces acknowledges the request within the required **5-second window** and queues the processing task.

![A workflow automation interface showing the execution and configuration of an HTTP request that revokes an API token using…](https://ap-marketing-media.fra1.cdn.digitaloceanspaces.com/uploads/d55bf56e-a650-41bf-a158-7c61b4ee1fc4/how-to-connect-a-reddit-integration-in-2026-step-535ff857.webp)

If the Linear API returns a 429 error during a mutation, the system uses its built-in retry logic to pause the flow until the complexity bucket resets, ensuring no data is lost during high-volume syncs.

For enterprise environments, Activepieces manages the promotion of these integrations through Git Sync and Release Management. This allows teams at organizations like MoneyGram and FundingSocieties to version their Linear workflows as code, moving them from development to production instances with validated credentials.

This replaces the risk of using personal API keys with managed service accounts and OAuth2 flows that are governed by centralized security policies.

## Frequently asked questions about Linear API?

### Does Linear support a REST API?
Linear doesn't provide a REST API for public consumption, requiring all developers to interface with their GraphQL endpoint for data operations. 

This architectural choice means you can't rely on standard HTTP verbs like GET or POST to specific resource paths. Instead, you must construct precise GraphQL queries and mutations, which demands a deeper understanding of the schema before the first successful call.

### How do I query for deleted issues via the API?
To maintain workspace performance and data integrity, the Linear API excludes deleted records from standard queries by default. To retrieve these records, you must specifically query the archive or check the archivedAt timestamp on the Issue object. 

Items are moved to an archived state rather than being immediately purged from the database. This ensures that historical data remains accessible for audit logs or recovery without cluttering the active project views or slowing down the primary execution engine.

### What is the maximum payload size for a Linear webhook?
Linear enforces a strict limit on the size of the JSON payload sent to your listener to prevent network congestion and timeout errors. 

If your automation triggers a massive update, such as bulk-editing hundreds of issues, the webhook will be truncated or fail to deliver. Your middleware must be designed to fetch missing details via a follow-up query rather than relying solely on the incoming notification.

### Can I use the API to export all workspace data?
The API allows for granular data retrieval but isn't designed as a bulk backup tool for entire workspaces. While you can paginate through issues and projects, attempting to crawl the entire graph for a large organization will likely trigger rate limits. 

For full-fidelity backups, you should use the dedicated export feature in the Linear settings dashboard. This built-in utility handles the extraction of all relational data and attachments into a portable format, bypassing the complexity constraints and point-based throttling of the GraphQL interface.

## Related reading

- [Notion Linear Integration: How to Connect Them (2026)](https://www.activepieces.com/blog/notion-linear-integration-how-to-connect-them-2026)
- [Best Linear Alternatives in 2026 (7 Picks Tested)](https://www.activepieces.com/blog/best-linear-alternatives-in-2026-7-picks-tested)
- [Linear App Pricing: Every Plan and Seat Cost (2026)](https://www.activepieces.com/blog/linear-app-pricing-every-plan-and-seat-cost-2026)
