import { Tabs, Callout, Steps } from "nextra/components";

# Linear

The Linear auth provider enables tools and agents to call [Linear APIs](https://linear.app/developers/graphql) on behalf of a user.

<Callout>
  Want to quickly get started with Linear in your agent or AI app? The pre-built
  [Arcade Linear MCP Server](/resources/integrations/productivity/linear) is what you want!
</Callout>

### What's documented here

This page describes how to use and configure Linear auth with Arcade.

This auth provider is used by:

- The [Arcade Linear MCP Server](/resources/integrations/productivity/linear), which provides pre-built tools for interacting with Linear
- Your [app code](#using-linear-auth-in-app-code) that needs to call Linear APIs
- Or, your [custom tools](#using-linear-auth-in-custom-tools) that need to call Linear APIs

## Configuring Linear auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own Linear app credentials. This way, your users will see your application's name requesting permission.

Before showing how to configure your Linear app credentials, let's go through the steps to create a Linear app.

### Create a Linear app

- It is **highly recommended** to first [create a new Linear workspace](https://linear.app/join) for the purpose of managing the OAuth2 Application, as each admin user will have access
- Create a new public OAuth2 Application in your [integration settings page](https://linear.app/settings/api/applications/new)
- Fill out your application specific information such as application name and description
- Choose the [scopes](https://linear.app/developers/oauth-2-0-authentication#redirect-user-access-requests-to-linear) (permissions) you need for your app
- Add the redirect URL generated by Arcade (see below) to the Callback URL field
- Toggle the **Public** switch if you want other workspaces to be able to use your application
- Copy the client ID and client secret to use below

Next, add the Linear app to Arcade.

## Configuring your own Linear Auth Provider in Arcade

<Tabs items={["Dashboard GUI"]}>
<Tabs.Tab>

### Configure Linear Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **Included Providers** tab at the top.
- In the **Provider** dropdown, select **Linear**.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "my-linear-provider").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your Linear app.
- Note the **Redirect URL** generated by Arcade. This must be added to your Linear app's Callback URL field.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

When you use tools that require Linear auth using your Arcade account credentials, Arcade will automatically use this Linear OAuth provider. If you have multiple Linear providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

</Tabs.Tab>
</Tabs>

## Using Linear auth in app code

Use the Linear auth provider in your own agents and AI apps to get a user token for Linear APIs. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for Linear APIs:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {22-26}
from arcadepy import Arcade
import httpx

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

"""
In this example, we will use Arcade to authenticate with Linear and
retrieve teams.

There is a tool for that in the Arcade Linear MCP Server, which simplifies
the process for you to interact with Linear either through our Python or
JavaScript SDKs or via LLM tool calling.

Below we are just showing how to use Arcade as an auth provider, if you ever
need to.
"""

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="linear",
    scopes=["read"],
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token

if not token:
    raise ValueError("No token found in auth response")

# Use the Linear GraphQL API
url = "https://api.linear.app/graphql"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}

query = """
query Teams {
  teams {
    nodes {
      id
      name
      key
    }
  }
}
"""

response = httpx.post(url, json={"query": query}, headers=headers)
data = response.json()
teams = data["data"]["teams"]["nodes"]

print(teams)
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {20-22}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable

const userId = "{arcade_user_id}";

/*
In this example, we will use Arcade to authenticate with Linear and
retrieve teams.

There is a tool for that in the Arcade Linear MCP Server, which simplifies
the process for you to interact with Linear either through our Python or
JavaScript SDKs or via LLM tool calling.

Below we are just showing how to use Arcade as an auth provider, if you ever
need to.
*/

// Start the authorization process
let authResponse = await client.auth.start(userId, "linear", {
  scopes: ["read"],
});

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

if (!authResponse.context.token) {
  throw new Error("No token found in auth response");
}

const token = authResponse.context.token;

// Use the Linear GraphQL API
const response = await fetch("https://api.linear.app/graphql", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: `
      query Teams {
        teams {
          nodes {
            id
            name
            key
          }
        }
      }
    `,
  }),
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const data = await response.json();
const teams = data.data.teams.nodes;

console.log(teams);
```

</Tabs.Tab>

</Tabs>

## Using Linear auth in custom tools

You can use the pre-built [Arcade Linear MCP Server](/resources/integrations/productivity/linear) to quickly build agents and AI apps that interact with Linear.

If the pre-built tools in the Linear MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the Linear API.

Use the `Linear()` auth class to specify that a tool requires authorization with Linear. The `context.authorization.token` field will be automatically populated with the user's Linear token:

```python {3-4,10-14,26}
from typing import Annotated, Any

from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import Linear

import httpx


@tool(requires_auth=Linear(scopes=["read"]))
async def get_teams(
    context: ToolContext,
) -> Annotated[dict[str, Any], "Teams in the workspace with member information"]:
    """Get Linear teams and team information including team members"""
    if not context.authorization or not context.authorization.token:
        raise ValueError("No token found in context")

    token = context.authorization.token
    url = "https://api.linear.app/graphql"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    }

    query = """
    query Teams {
      teams {
        nodes {
          id
          name
          key
        }
      }
    }
    """

    async with httpx.AsyncClient() as client:
        resp = await client.post(url, json={"query": query}, headers=headers)
        resp.raise_for_status()
        data = resp.json()
        teams = data["data"]["teams"]["nodes"]
        return teams
```