# Linear Ticketing Provider Configuration Guide

This guide explains how to configure a Linear Ticketing integration.

## Overview

Linear uses personal API keys to authenticate API requests. Each key is scoped to the workspace of the user who creates it.

## Prerequisites

- A Linear account with access to the workspace you want to integrate
- Permissions to create API keys in that workspace


## Authentication Steps

### 1. Generate a Personal API Key

1. Select the workspace name in the top left corner
2. Select **Settings**
3. Select **Security & access**
4. Find **Personal API Keys** and select **New API Key**
5. Enter a key name and configure the desired permissions
6. Note down the API key in a secure place — it is shown only once


The available permissions are Read, Write, Create Issues, and Create Comments. Enable the permissions appropriate for your use case.

For reference, see the [Linear API documentation on personal API keys](https://linear.app/developers/graphql#personal-api-keys).

> **Note:** Linear API keys start with `lin_api_`. If your key does not match this format, verify you copied it correctly.


### 2. (Optional) Identify Your Default Team ID

If you want ticket creation requests to default to a specific team without requiring it in each request:

- From the sidebar, select the team name. The URL will look like `https://linear.app/acmecorp/team/DEV/overview` — in this example, `DEV` is the team ID.
- Alternatively, select the three-dot menu (`...`) next to the team name, select **Team settings** > **General**, and find the **Identifier** field.


## Configure the Integration

Create your integration by supplying the following values:

| Parameter | Description |
|  --- | --- |
| **Credential** | The personal API key generated in step 1 |
| **API URL** | GraphQL API endpoint. Defaults to `https://api.linear.app/graphql`. Only change this for custom deployments. |
| **Default Team ID** | Optional. The Linear team ID to use when creating tickets if no team is specified in the request. |


## Verification

After configuring the integration, test the connection to ensure proper functionality.

## Troubleshooting

If you encounter any issues:

- Verify your API key starts with `lin_api_` and has not been revoked
- Confirm your Linear account has access to the target workspace
- Check that the API key owner has permissions to the teams and projects you need


## Additional Resources

- [Linear API Documentation](https://developers.linear.app/)
- [Personal API Keys](https://linear.app/developers/graphql#personal-api-keys)