Skip to content

Docs: Linear Auth Provider #351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 19, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions examples/code/integrations/linear/config_provider.engine.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
auth:
providers:
- id: default-linear
description: "The default Linear provider"
enabled: true
type: oauth2
provider_id: linear
client_id: ${env:LINEAR_CLIENT_ID}
client_secret: ${env:LINEAR_CLIENT_SECRET}
21 changes: 21 additions & 0 deletions examples/code/integrations/linear/custom_auth.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
import { Arcade } from "@arcadeai/arcadejs";

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

const userId = "{arcade_user_id}";

// 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);

const token = authResponse.context.token;
// Do something interesting with the token...
24 changes: 24 additions & 0 deletions examples/code/integrations/linear/custom_auth.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
from arcadepy import Arcade

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

user_id = "{arcade_user_id}"

# 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
# Do something interesting with the token...
37 changes: 37 additions & 0 deletions examples/code/integrations/linear/custom_tool.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
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"""
token = context.get_auth_token_or_empty()
url = "https://api.linear.app/graphql"
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Accept": "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
7 changes: 7 additions & 0 deletions pages/home/auth-providers/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,13 @@ For more information on how to customize your auth provider, select an auth prov
link="/home/auth-providers/hubspot"
category="Auth"
/>
<ToolCard
name="Linear"
image="linear.svg"
summary="Authorize tools and agents with Linear"
link="/home/auth-providers/linear"
category="Auth"
/>
<ToolCard
name="LinkedIn"
image="linkedin"
Expand Down
152 changes: 152 additions & 0 deletions pages/home/auth-providers/linear.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
import { Tabs } from "nextra/components";

# Linear auth provider

The Linear auth provider enables tools and agents to call [Linear APIs](https://linear.app/developers/graphql) on behalf of a user. Behind the scenes, the Arcade Engine and the Linear auth provider seamlessly manage Linear OAuth 2.0 authorization for your users.

### What's documented here

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

This auth provider is used by:

- Your [app code](#using-linear-auth-in-app-code) that needs to call the Linear API
- Or, your [custom tools](#using-Linear-auth-in-custom-tools) that need to call the Linear API

## Configuring Linear auth

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.

You can use your own Linear credentials in both the Arcade Cloud and in a [self-hosted Arcade Engine](/home/local-deployment/install/local) instance.

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.
- Create a new public OAuth2 Application in your [integration's settings page](https://linear.app/settings/api/applications/new).
- Fill out your application specific information such as application name and description.
- Set the Callback URL to: `https://cloud.arcade.dev/api/v1/oauth/callback`
- Toggle the **Public** switch to enable public access to the application if you want other workspaces to be able to use your application.
- Once you complete creating your integration, copy the client ID and client secret to use below.

Next, add the Linear app to your Arcade Engine configuration. You can do this in the Arcade Dashboard, or by editing the `engine.yaml` file directly (for a self-hosted instance).

## Configuring your own Linear Auth Provider in Arcade

There are two ways to configure your Linear app credentials in Arcade:

1. From the Arcade Dashboard GUI
2. By editing the `engine.yaml` file directly (for a self-hosted Arcade Engine)

We show both options step-by-step below.

<Tabs items={["Dashboard GUI", "Engine Configuration YAML"]}>
<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 **OAuth** section of the Arcade Dashboard left-side menu, click **Providers**.
- 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.

#### Create the provider

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

</Steps>

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

</Tabs.Tab>
<Tabs.Tab>

### Configuring Linear auth in self-hosted Arcade Engine configuration

<Steps>

### Set environment variables

Set the following environment variables:

```bash
export LINEAR_CLIENT_ID="<your client ID>"
export LINEAR_CLIENT_SECRET="<your client secret>"
```

Or, you can set these values in a `.env` file:

```bash
LINEAR_CLIENT_ID="<your client ID>"
LINEAR_CLIENT_SECRET="<your client secret>"
```

<Tip>
See [Engine configuration](/home/local-deployment/configure/engine) for more information on how
to set environment variables and configure the Arcade Engine.
</Tip>

### Edit the Engine configuration

Edit the `engine.yaml` file and add a `Linear` item to the `auth.providers` section:

```yaml file=<rootDir>/examples/code/integrations/linear/config_provider.engine.yaml {3-9}

```

</Steps>

</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 the Linear API. See [authorizing agents with Arcade](/home/auth/how-arcade-helps) to understand how this works.

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

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

```python file=<rootDir>/examples/code/integrations/linear/custom_auth.py {8-14}

```

</Tabs.Tab>

<Tabs.Tab>

```javascript file=<rootDir>/examples/code/integrations/linear/custom_auth.js {8-10}

```

</Tabs.Tab>

</Tabs>

## Using Linear auth in custom tools

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

If the pre-built tools in the Linear toolkit don't meet your needs, you can author your own [custom tools](/home/build-tools/create-a-toolkit) 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 file=<rootDir>/examples/code/integrations/linear/custom_tool.py

```
Loading