Skip to main content

Linear

Linear is a modern issue tracking and project management tool designed for software teams to streamline workflows and ship faster. It helps teams plan, organize, and track their work with a focus on speed and user experience.

Authentication Types​

Linear supports 2 authentication methods:

  • OAuth - Create your own Linear OAuth application with custom scopes. Every user connects with their Linear account.

    • Pros: Full control, per-user tracking, production-ready, refresh tokens
    • Cons: Requires 2-3 minute setup

  • API Key - Use a personal API key for all users.

    • Pros: Quick setup, simple configuration
    • Cons: Less secure, no per-user tracking, actions appear as single user

Setting up OAuth​

  1. Go to https://linear.app/settings/api

  2. Scroll down to the OAuth Applications section

  3. Click Create New

  4. Fill in the application details:

    • Name: Enter a name for your application (e.g., "Webrix Integration")
    • Description: Optional description of your application
    • Callback URLs: Copy the Redirect URL from Webrix and paste it here
tip

The redirect URL in Webrix can be found when you configure the Linear connector. Make sure to copy it exactly as shown.

  1. Copy the Client ID and Client Secret from the application details

  2. In Webrix, go to Integrations → New → Built-in → Linear

  3. Paste the Client ID and Client Secret into the respective fields

  4. Select relevant scopes:

    • read - (Default) Read access for the user's account. This scope will always be present.
    • write - Write access for the user's account. If your application only needs to create comments, use a more targeted scope
    • issues:create - Allows creating new issues and their attachments
    • comments:create - Allows creating new issue comments
    • timeSchedule:write - Allows creating and modifying time schedules
    • admin - Full access to admin level endpoints. You should never ask for this permission unless it's absolutely needed

  5. Click Save Changes and then Connect to authorize the integration

Setting up API Key​

  1. Go to https://linear.app/settings/api

  2. Scroll to the Personal API Keys section

  3. Click Create new key

  4. Enter a Label for your key (e.g., "Webrix Integration")

  5. Click Create key

  6. Copy the API key immediately (it won't be shown again)

warning

Keep your API key secure! Never share it publicly or commit it to version control. Anyone with this key has full access to your Linear account.

  1. In Webrix, go to Integrations → New → Built-in → Linear

  2. Select API Key as the authentication method

  3. Paste your API key into the token field

  4. Click Save to complete the setup

Common Use Cases​

Issue Management​

  • Create and assign issues to team members
  • Update issue status, priority, and labels
  • Search for issues across teams
  • Add comments for collaboration

Project Planning​

  • Create projects to organize related work
  • Track project progress and milestones
  • Manage project timelines and target dates
  • Assign project leads and team members

Cycle (Sprint) Management​

  • Create and manage cycles for time-boxed work
  • Track cycle progress and completion
  • Plan upcoming cycles with issue assignments
  • Review completed cycles and metrics

Workflow Automation​

  • List available workflow states for teams
  • Move issues through different states
  • Automate issue creation from external events
  • Sync issue status with other tools

Troubleshooting​

Redirect URI Mismatch Error​

Cause: The redirect URL configured in Linear doesn't match the one used by Webrix.

Solution:

  1. Go to your Linear OAuth application settings
  2. Check the Callback URLs field
  3. Copy the exact redirect URL from Webrix
  4. Add it to the callback URLs in Linear (you can have multiple URLs)
  5. Save the changes and try connecting again

Invalid Client ID or Client Secret​

Cause: The credentials were copied incorrectly or the OAuth application was deleted.

Solution:

  1. Verify you copied the entire Client ID and Client Secret without extra spaces
  2. Go to https://linear.app/settings/api and check if your OAuth application still exists
  3. If needed, regenerate the client secret and update it in Webrix
  4. Ensure you're using credentials from the correct Linear workspace

Insufficient Permissions Error​

Cause: The API key or OAuth token doesn't have the required scopes for the operation.

Solution:

For OAuth:

  1. Check which scopes you selected when creating the OAuth application
  2. Go to the Linear OAuth application settings and add the missing scopes
  3. Reconnect the integration in Webrix to get a new token with updated scopes

For API Key:

  1. Personal API keys have full access to your account
  2. If you're seeing permission errors, check if your Linear user has access to the team or project you're trying to modify
  3. Ensure you're not trying to access archived or restricted resources

Token Expired or Refresh Failed​

Cause: OAuth access tokens expire and need to be refreshed. Linear tokens expire after the time period specified when issued.

Solution:

  1. Linear OAuth applications created after October 1, 2025 have refresh tokens enabled by default
  2. If using an older OAuth application, you may need to recreate it to get refresh token support
  3. Webrix should automatically refresh tokens, but you can try disconnecting and reconnecting if issues persist
  4. For API keys, they don't expire unless manually revoked - generate a new one if needed

GraphQL Query Errors​

Cause: Invalid GraphQL query syntax or trying to access fields that don't exist.

Solution:

  1. Linear's GraphQL schema is versioned and may change over time
  2. Check the Linear API documentation for current field names
  3. Verify that IDs you're passing (teamId, issueId, etc.) are correct and the resources exist
  4. Use the Apollo Studio explorer to test queries

Rate Limiting​

Cause: Making too many API requests in a short time period.

Solution:

  1. Linear implements rate limiting to ensure API stability
  2. Reduce the frequency of requests or implement exponential backoff
  3. Use pagination cursors to fetch data in smaller batches
  4. Consider caching frequently accessed data

Best Practices​

  1. Use OAuth for production - OAuth provides better security and per-user tracking compared to API keys

  2. Request minimal scopes - Only request the OAuth scopes your integration actually needs

  3. Use team-specific filters - When querying issues or projects, filter by teamId to improve performance

  4. Leverage pagination - Use cursor-based pagination for large datasets to avoid timeouts

  5. Handle GraphQL errors - Always check the response for errors array, as GraphQL returns 200 even with errors

  6. Use issue identifiers - When referencing issues, use the human-readable identifier (e.g., "ENG-123") instead of UUIDs when possible

  7. Keep API keys secure - Never expose API keys in client-side code or public repositories