Docs: Linear Auth Provider

examples/code/integrations/linear/config_provider.engine.yaml

@@ -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}

examples/code/integrations/linear/custom_auth.js

@@ -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...

examples/code/integrations/linear/custom_auth.py

@@ -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...

examples/code/integrations/linear/custom_tool.py

@@ -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

pages/home/auth-providers/index.mdx

@@ -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"

pages/home/auth-providers/linear.mdx

@@ -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
+
+```