# Linear

## Linear – Connector Configuration

### Step 1: Access Linear & Create Developer Account

* Sign in to your Linear workspace at [Linear](https://linear.app/)
* 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:

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

Example:

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

2. **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)
3. **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](https://802996127-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FIAGKHlIqVKJe9agnFr14%2Fuploads%2Fgit-blob-f20a47d6fa461f670beb84ea9033fa13faa78982%2Flinear1.png?alt=media)

***

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:

```graphql
{
  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**:

```graphql
{
  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](https://developers.linear.app/)
* [GraphQL API Reference](https://studio.apollographql.com/public/Linear-API/variant/current/home)
* [OAuth Documentation](https://developers.linear.app/docs/oauth)
* [Webhook Guide](https://developers.linear.app/docs/webhooks)
* [Rate Limiting](https://developers.linear.app/docs/rate-limiting)
* [GraphQL Best Practices](https://developers.linear.app/docs/graphql-best-practices)

***