Linear

Productivity

Manage issues, projects, and workflows in Linear

Linear developer console OAuth setup guide API docs

Installing Linear creates a resource for the upstream API and the OAuth provider Keycard needs to mint tokens for it. Your app calls Keycard’s token exchange, gets back a token scoped to Linear, and uses it to call the API directly. Every exchange is governed by your zone’s identity provider, access policies, and audit log - the OAuth client secret stays inside Keycard.

Scopes

SCOPES

OAuth permissions Keycard requests on install. Override or add scopes in Console.

read: default
write: default
issues:create
comments:create
timeSchedule:write
admin
app:assignable
app:mentionable
customer:read
customer:write
initiative:read
initiative:write

Install

INSTALL

Add Linear to your zone so your app can exchange tokens for it.

Step 1 - Start the install in Keycard Console

In your zone’s Keycard Console, go to Resources -> Explore Resources.
Search for Linear and click into the catalog entry.
The install dialog shows a Redirect URI. Copy it - you’ll paste it into Linear in Step 2. Leave this Keycard tab open.

Step 2 - Create the OAuth app for Linear

Create a Linear OAuth application

Go to Linear Settings → API → Applications
Fill in:
- Application name: A descriptive name
- Redirect callback URLs: The redirect URI provided by Keycard
- Description: Optional description of your integration
Click Create

Get credentials

After creating the application, note the Client ID and Client Secret

Step 3 - Finish the install in Keycard Console

Switch back to the Keycard install dialog you left open in Step 1.
Paste the Client ID and Client Secret from Step 2.
Click Add Linear. The resource is provisioned and your app can start exchanging tokens for it.

Use Linear from your code

USE FROM CODE

Call Linear from your application with a Keycard-issued token scoped to this resource.

After installing Linear, your application exchanges a Keycard-issued access token for a token scoped to this resource. Pass the user’s access token as the subject_token.

Python
TypeScript

from keycardai.oauth import Client, BasicAuth, TokenType
import requests

# Exchange the user's Keycard token for a Linear token.
with Client(
    "https://<zone-id>.keycard.cloud",
    auth=BasicAuth("<your-client-id>", "<your-client-secret>"),
) as client:
    response = client.exchange_token(
        subject_token=user_access_token,
        subject_token_type=TokenType.ACCESS_TOKEN,
        resource="https://api.linear.app",
    )

# Call Linear directly with the exchanged token.
r = requests.get(
    "https://api.linear.app/<endpoint>",
    headers={"Authorization": f"Bearer {response.access_token}"},
)

import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";

const client = new TokenExchangeClient("https://<zone-id>.keycard.cloud", {
  clientId: "<your-client-id>",
  clientSecret: "<your-client-secret>",
});

const response = await client.exchangeToken({
  subjectToken: userAccessToken,
  resource: "https://api.linear.app",
});

// Call Linear directly with the exchanged token.
const res = await fetch("https://api.linear.app/<endpoint>", {
  headers: { Authorization: `Bearer ${response.accessToken}` },
});

See the OAuth SDK → Token Exchange reference for the full client API.

Troubleshooting

TROUBLESHOOTING

Common errors when wiring Linear into your zone.

Error: Authentication required

The access token is invalid or expired. Reconnect the provider in Keycard Console. Linear tokens have a fixed expiry - Keycard handles refresh automatically if the provider issued a refresh token.

GraphQL errors in response

If the test returns a 200 status but the response contains GraphQL errors, check:

The granted scopes include read (required for the viewer query)
The user has an active Linear account

Next steps

NEXT STEPS

What to do once Linear is installed.

Now do this

Call Linear from your code - see the Use Linear from your code section above for Python and TypeScript samples.

Recommended

Decide who can use it - write access policies scoped to the Linear resource so only the right users and apps reach the API.
Watch the calls - every token exchange and downstream call lands in your audit log with user identity, resource, and policy decision.

Optional

Add MCP access too - install the Linear MCP server for AI agents that need Linear’s tools, not just the REST API.