Linear

Linear – Connector Configuration

Step 1: Access Linear & Create Developer Account

• Sign in to your Linear workspace at Linear

• You need admin permissions in your Linear workspace to create applications

• Navigate to your workspace settings

⚠️ Note: Only workspace administrators can create OAuth applications in Linear.

---

Step 2: Create Your OAuth Application

1. Navigate to API Settings:

   • Go to Settings → Account → API

   • Or visit: https://linear.app/[your-workspace]/settings/api

2. Create New Application:

   • Click "Create new" under OAuth applications

   • Fill in the application details:

     • Application name (e.g., "Appmixer Integration")

     • Description - Brief description of your integration

     • Website URL - Your organization's website

     • Callback URLs - OAuth redirect endpoints

---

Step 3: Configure OAuth Settings

1. Set Callback URLs:

   • Add your OAuth callback URL in the "Callback URLs" field

   • For Appmixer, set the redirect URI to:

https://[YOUR_API_BASE]/auth/linear/callback

Example:

https://api.appmixer.com/auth/linear/callback

1. Configure Scopes:

   • Linear uses specific scopes to control access:

     • read - Read access to issues, projects, teams, and users

     • write - Write access to create and update issues and comments

     • admin - Administrative access (use with caution)

2. Application Details:

   • Application name: Your integration name

   • Description: Purpose of your integration

   • Website: Your application or company website

---

Step 4: Copy Your OAuth Credentials

After creating your application, you'll receive:

• Client ID - Your OAuth application identifier

• Client Secret - Your OAuth application secret (keep this secure!)

⚠️ Important: Store your Client Secret securely and never expose it in client-side code!

---

Step 5: Webhook Configuration (Optional)

Linear supports webhooks for real-time updates:

1. Create Webhook:

   • In API settings, go to "Webhooks" section

   • Click "Create webhook"

2. Configure Webhook Settings:

   • URL: Your endpoint to receive webhook notifications

   • Label: Descriptive name for the webhook

   • Secret: Optional signing secret for verification

3. Select Resources:

   • Choose which resources trigger webhooks:

     • Issue - Issue creation, updates, deletion

     • Comment - Comment creation and updates

     • Project - Project changes

     • ProjectUpdate - Project status updates

---

Step 6: Personal API Key (Alternative)

For server-to-server integrations, you can use personal API keys:

1. Generate Personal API Key:

   • Go to Settings → Account → API

   • Click "Create key" under Personal API keys

   • Add a descriptive label

   • Copy the generated key immediately (it won't be shown again)

⚠️ Note: Personal API keys have the same permissions as your user account.

---

Step 7: Connector Configuration

1. Go to the Appmixer BackOffice -> Configuration.

2. Add new configuration: acme:linear.

3. Add your clientId and clientSecret keys with values from Linear.

alt text

---

1. Test OAuth Flow:

   • Linear authorization URL: https://linear.app/oauth/authorize

   • Required parameters: client_id, redirect_uri, response_type=code, scope

2. API Testing:

   • Linear GraphQL API endpoint: https://api.linear.app/graphql

   • Include Authorization: Bearer <access_token> header

   • Test with a simple query like fetching the viewer:

{
  viewer {
    id
    name
    email
  }
}

---

Step 8: GraphQL API Overview

Linear uses GraphQL exclusively:

Common Queries:

• Issues: issues, issue

• Teams: teams, team

• Projects: projects, project

• Users: users, user

Common Mutations:

• Create Issue: issueCreate

• Update Issue: issueUpdate

• Create Comment: commentCreate

Example Issue Query:

{
  issues(first: 10) {
    nodes {
      id
      title
      description
      state {
        name
      }
      assignee {
        name
      }
    }
  }
}

---

Step 9: Rate Limits

Rate Limits:

• Complexity-based limiting: Each query has a complexity score

• Maximum complexity: 1000 points per query

• Rate limit: 2000 requests per hour per access token

• Burst limit: 120 requests per minute

---

Useful Links

• Linear API Documentation

• GraphQL API Reference

• OAuth Documentation

• Webhook Guide

• Rate Limiting

• GraphQL Best Practices

---