Install and configure Linear SDK/CLI authentication.
Use when setting up a new Linear integration, configuring API keys,
OAuth2 flows, or initializing LinearClient in your project.
Trigger: "install linear", "setup linear", "linear auth",
"configure linear API key", "linear SDK setup", "linear OAuth".
Install and configure Linear SDK/CLI authentication.
Use when setting up a new Linear integration, configuring API keys,
OAuth2 flows, or initializing LinearClient in your project.
Trigger: "install linear", "setup linear", "linear auth",
"configure linear API key", "linear SDK setup", "linear OAuth".
Designed for Claude Code, also compatible with Codex and OpenClaw
Linear Install & Auth
Overview
Install the @linear/sdk TypeScript SDK and configure authentication for the Linear GraphQL API at https://api.linear.app/graphql. Supports personal API keys for scripts and OAuth 2.0 (with PKCE) for user-facing apps.
Prerequisites
Node.js 18+ (SDK is TypeScript-first, works in any JS environment)
Package manager (npm, pnpm, or yarn)
Linear account with workspace access
For API key: Settings > Account > API > Personal API keys
For OAuth: Create app at Settings > Account > API > OAuth applications
Available OAuth scopes:read, write, issues:create, admin, initiative:read, initiative:write, customer:read, customer:write.
Step 4: Token Refresh (OAuth)
asyncfunctionrefreshAccessToken(refreshToken: string): Promise<string> {
const response = awaitfetch("https://api.linear.app/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: newURLSearchParams({
grant_type: "refresh_token",
refresh_token: refreshToken,
client_id: process.env.LINEAR_CLIENT_ID!,
client_secret: process.env.LINEAR_CLIENT_SECRET!,
}),
});
if (!response.ok) {
thrownewError(`Token refresh failed: ${response.status}`);
}
const tokens = await response.json();
// Store new refresh_token — Linear rotates it on each refreshawaitsaveTokens(tokens.access_token, tokens.refresh_token);
return tokens.access_token;
}
Step 5: Validate Configuration on Startup
functionvalidateLinearConfig(): void {
const key = process.env.LINEAR_API_KEY;
if (!key) thrownewError("LINEAR_API_KEY environment variable is required");
if (!key.startsWith("lin_api_")) thrownewError("LINEAR_API_KEY must start with lin_api_");
if (key.length < 30) thrownewError("LINEAR_API_KEY appears truncated");
}
// Call before creating clientvalidateLinearConfig();
