Linear API Key: How to Generate and Use It (GraphQL Guide for Developers)

April 23, 2026

What is a Linear API key?

A Linear API key is a long-lived credential used to authenticate requests to Linear's GraphQL API. It represents your Linear account and is sent in the Authorization header (without Bearer) to https://api.linear.app/graphql for every request.

Unlike OAuth tokens, API keys are static, user-scoped, and do not expire automatically.

Why Linear API keys matter

Linear is GraphQL-only. That changes how integrations work:

• All reads and writes go through a single endpoint
• Your API key controls everything your integration can access
• Permissions come from the user who created the key
• Errors, rate limits, and performance are tied to how your queries are structured

If your key or request is misconfigured, every operation fails—not just a specific endpoint.

API keys are the fastest way to:

• automate workflows
• build internal tools
• integrate Linear into your backend systems

How to get a Linear API key

Quick steps

1. Log in to Linear (https://linear.app)
2. Go to Settings → Account → Security & Access
3. Find Personal API keys
4. Click Create API key
5. Name the key
6. Copy it immediately and store it securely

Linear only shows the key once. If you lose it, you must generate a new one.

Example: using a Linear API key

cURL

curl -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: lin_api_your_key_here" \
  --data '{ "query": "{ viewer { id name email } }" }'

Key details

• Endpoint: https://api.linear.app/graphql
• Method: always POST
• Header: Authorization: lin_api_... (no Bearer)

If you accidentally send Bearer lin_api_..., authentication will fail.

What a Linear API key actually represents

A Linear API key is:

• User-scoped — it inherits the permissions of the user who created it
• Long-lived — it does not expire unless revoked
• Permission-bound — can be restricted by:
  • read/write/admin scopes
  • team access

This means your integration is effectively acting as that user.

How Linear authentication works

Linear supports two authentication methods:

Personal API key

• Static credential
• Passed as:

  Authorization: lin_api_...
  

• Best for:
  • scripts
  • CI/CD
  • internal tools

OAuth 2.0

• User authorization flow
• Access token + refresh token
• Passed as:

  Authorization: Bearer <token>
  

• Required for:
  • multi-tenant SaaS
  • customer integrations

Linear API key vs OAuth

• One user, backend system → API key
• Multiple users, external product → OAuth

How Linear differs from REST APIs

This is where most developers get tripped up.

Key implications

• You must design queries carefully, not just endpoints
• Errors may appear in the response body even when status = 200
• Overly complex queries can fail even if auth is correct

Common Linear API key use cases

API keys are ideal for:

Internal dashboards

• Pull issues, teams, and metrics into custom UIs

CI/CD automation

• Create issues from failed builds
• Update status during deployments

Support workflows

• Convert tickets into Linear issues
• Sync comments and updates

Reporting pipelines

• Export data to warehouses
• Generate weekly engineering reports

Bots and agents

• AI tools that read/write issues server-side

Linear API key not working: common fixes

UNAUTHENTICATED

• Missing Authorization header
• Wrong format (Bearer used incorrectly)
• Invalid or revoked key

Fix:

Use:

Authorization: lin_api_...

FORBIDDEN

• Insufficient permissions
• Accessing restricted teams

Fix:

Regenerate key with proper permissions

Rate limited (RATELIMITED)

• Query too complex
• Too many requests

Fix:

• reduce fields
• paginate properly
• implement retries

GraphQL errors with HTTP 200

• Query failed, not the request

Fix:

Always inspect:

errors[].extensions.code

Quick checklist

• Key starts with lin_api_
• Correct endpoint
• Correct headers
• Permissions match operation
• Query is valid

Linear API rate limits (quick overview)

Linear uses two systems:

Request limits

• ~5,000 requests per hour per user

Complexity limits

• Each query has a cost based on:
  • fields
  • objects
  • pagination depth

What to do

• Use pagination (first: N)
• limit nested fields
• implement exponential backoff

Security best practices

Store keys securely

• environment variables
• secrets managers

Never expose in frontend

• keys are long-lived and high-risk

Rotate regularly

• every 30–90 days for sensitive systems

Apply least privilege

• restrict teams and permissions

GraphQL challenges at scale

Linear's API introduces new complexity:

Complexity-based limits

• queries can fail before execution if too expensive

Cursor pagination

• no offsets
• must track endCursor

Errors in 200 responses

• cannot rely on HTTP status

No caching by default

• all requests are POST

N+1 query problems

• inefficient query patterns increase cost

Why auth becomes difficult in SaaS

API keys don't scale for customer-facing products.

You must handle:

• OAuth flows per user
• token storage and encryption
• refresh logic
• scope differences
• rate limits per user

This turns auth into a system, not a setup step.

Building across integrations (Unified context)

When Linear is one of many integrations, complexity compounds:

• different auth models
• different APIs (GraphQL vs REST)
• different rate limits
• different error handling

Unified standardizes this:

• one authorization model
• one API surface
• consistent data structures
• no per-integration auth logic

Instead of handling Linear separately, you integrate once and reuse the same pattern across systems.

FAQs

What is a Linear API key?

A user-scoped credential used to authenticate requests to Linear's GraphQL API.

How is it different from OAuth?

API keys are static and user-based. OAuth is dynamic, scoped, and multi-user.

Does a Linear API key expire?

No. It remains valid until manually revoked.

Can I use it in frontend apps?

No. It should only be used in backend systems.

Why does Linear return HTTP 200 for errors?

Because GraphQL returns errors in the response body, not always via HTTP status.

Linear API authentication: simple mental model

• API key = user-level access
• OAuth = multi-user access
• Linear = GraphQL-only API
• auth happens at a single endpoint

Key takeaways

• Linear API keys are simple but powerful credentials for GraphQL access
• They are best for internal and backend use cases
• OAuth is required for multi-tenant SaaS integrations
• GraphQL changes how you handle:
  • errors
  • rate limits
  • data fetching
• Most integration issues come from:
  • incorrect headers
  • permission mismatches
  • query complexity

If you're integrating Linear into a product, authentication is not just setup—it shapes how your entire integration behaves.

→ Start your 30-day free trial

→ Book a demo