How to set up API integrations on Linear

intermediate 8 min read Updated 2026-03-18

Quick Answer

Setting up API integrations on Linear involves creating an API key in your workspace settings, configuring the appropriate scopes, and implementing the Linear GraphQL API in your application. You can create personal API keys for individual use or OAuth applications for team-wide integrations.

Try Linear Full Linear Review

Prerequisites

Linear workspace admin access
Basic understanding of APIs
Development environment for testing
Application or service to integrate with Linear

Step-by-Step Instructions

Access Linear Settings

Navigate to your Linear workspace and click on your profile avatar in the bottom-left corner. Select Settings from the dropdown menu, then choose API from the left sidebar.

Make sure you have admin permissions in your workspace to access API settings

Create a Personal API Key

In the API settings page, scroll to the Personal API keys section and click Create key. Enter a descriptive name for your API key (e.g., "Slack Integration" or "Custom Dashboard") and optionally set an expiration date for security purposes.

Use descriptive names to easily identify different API keys later

Configure API Key Scopes

Select the appropriate scopes for your integration:

read - View issues, projects, and other data
write - Create and update issues, comments, and labels
admin - Full workspace access including settings

Choose the minimum required permissions for your use case.

Follow the principle of least privilege - only grant the permissions your integration actually needs

Copy and Secure Your API Key

After creating the key, immediately copy the generated API token using the Copy button. Store this key securely in your application's environment variables or secrets manager. The key will only be displayed once and cannot be retrieved later.

Never commit API keys to version control - use environment variables instead

Set Up Your Development Environment

Install the Linear SDK for your programming language or prepare to make direct GraphQL requests. For JavaScript/Node.js, install the official SDK:

npm install @linear/sdk

For other languages, prepare your HTTP client to make requests to https://api.linear.app/graphql.

The Linear SDK provides TypeScript definitions and simplifies API interactions

Initialize the Linear Client

Set up your Linear client with the API key. For the Linear SDK:

import { LinearClient } from '@linear/sdk';

const linearClient = new LinearClient({
  apiKey: process.env.LINEAR_API_KEY
});

For direct GraphQL requests, include the API key in the Authorization header as Bearer YOUR_API_KEY.

Test your connection with a simple query like fetching your user information first

Test Your Integration

Make a test API call to verify your setup is working correctly. Try fetching your workspace information:

const me = await linearClient.viewer;
console.log(`Connected as: ${me.name}`);

If successful, you should see your user details returned from the Linear API.

Start with read-only operations to test your connection before implementing write operations

Configure Webhooks (Optional)

For real-time updates, set up webhooks in the Webhooks section of your API settings. Click Create webhook, enter your endpoint URL, and select the events you want to receive (issue updates, comment creation, etc.). Linear will send POST requests to your endpoint when these events occur.

Implement webhook signature verification to ensure requests are coming from Linear

Common Issues & Troubleshooting

API key authentication fails with 401 Unauthorized error

Verify your API key is correctly set in your environment variables and that you're including it in the Authorization: Bearer YOUR_API_KEY header. Check that the API key hasn't expired.

GraphQL queries return permission denied errors

Review your API key scopes in Linear settings. Ensure your key has the necessary permissions (read, write, or admin) for the operations you're trying to perform.

Webhook events are not being received

Check that your webhook endpoint is publicly accessible and returns a 200 status code. Verify the webhook URL is correct in Linear settings and that your server is properly handling POST requests.

Rate limiting errors when making API calls

Implement exponential backoff and respect Linear's rate limits. The API allows up to 2000 requests per hour per API key. Add delays between requests and handle 429 status codes gracefully.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official Linear website before purchasing.

Visit Linear View Linear Pricing