HomeCustomizing AuthLinear

Linear auth provider

The Linear auth provider enables tools and agents to call Linear APIs 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 that needs to call the Linear API
  • Or, your 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 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 for the purpose of managing the OAuth2 Application.
  • Create a new public OAuth2 Application in your integration’s settings page.
  • 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.

Configure Linear Auth Using the Arcade Dashboard GUI

Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to 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.

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 for more information.

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 to understand how this works.

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

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

Using Linear auth in custom tools

You can use the pre-built Arcade Linear toolkit 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 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:

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
HubspotLinkedin