# 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](/files/miVYlVRGqjmgEudCS81j)

***

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)

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appmixer.com/connector-configuration/linear.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.