How to Fix Linear API Key Not Working or Returning 401

In this tutorial, you'll learn about How to Fix Linear API Key Not Working or Returning 401. We cover key concepts, practical examples, and best practices.

Linear API keys authenticate programmatic access to your Linear workspace. When an API request returns 401 Unauthorized or 403 Forbidden, the key is invalid, revoked, or lacks the required permissions for the requested resource.

The Problem

Your API call to https://api.linear.app/<a href="/apis/graphql/">graphql</a>:

query { viewer { id name } }

Returns:

{
  "errors": [{"message": "401: Unauthorized"}]
}

Wrong approach — hardcoding a new key directly in the source code.

The Fix

Verify the key is active:

1. Linear → Settings → API → Personal API keys
2. Find your key in the list
3. If it shows "Revoked" or is not listed, create a new key
4. Copy the new key immediately (keys are only shown once)

Check the key has the required scope:

1. When creating a key, scopes are shown: Admin, Read, Write, Issues, etc.
2. If your key was created with "Read" scope but you are trying to mutate data, it will fail
3. Create a new key with the appropriate scopes for your use case
4. Delete old keys with insufficient scopes

For organization-level API access, use a separate admin key:

1. Admin keys have access to all teams
2. User keys only access teams the user is a member of
3. For workspace-wide automation, use an admin account's API key

Expected output:

API returns 200 with the requested data
GraphQL mutations succeed with proper authorization
Responses include the expected fields without errors

Prevention Tips

• Create separate API keys for each application or integration
• Use the minimum required scope for each key
• Rotate keys every 90 days
• Store keys in environment variables or a secrets manager
• Monitor key usage in Linear's API logs
• Revoke keys immediately when an application is decommissioned

Common Mistakes with api key

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world LINEAR code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

Related: DodaTech's API Key Manager securely generates, stores, and rotates Linear API keys, with usage monitoring and automatic revocation for inactive keys. Use with DodaZIP for encrypted key storage.