Secure API key management and OAuth best practices for Linear.
Use when setting up authentication securely, implementing OAuth flows,
or hardening Linear integrations.
Trigger with phrases like "linear security", "linear API key security",
"linear OAuth", "secure linear integration", "linear secrets management".
Secure authentication patterns for Linear integrations: API key management, OAuth 2.0 with PKCE, token refresh (mandatory for new apps after Oct 2025), webhook HMAC-SHA256 signature verification, and secret rotation.
Prerequisites
Linear account with API access
Understanding of environment variables and secret management
Familiarity with OAuth 2.0 and HMAC concepts
Instructions
Step 1: Secure API Key Storage
// NEVER hardcode keys
// BAD:
// const client = new LinearClient({ apiKey: "lin_api_xxxx" });
// GOOD: environment variable
import { LinearClient } from "@linear/sdk";
const client = new LinearClient({
apiKey: process.env.LINEAR_API_KEY!,
});
function validateConfig(): void {
const key = process.env.LINEAR_API_KEY;
if (!key) throw new Error("LINEAR_API_KEY is required");
if (!key.startsWith("lin_api_")) throw new Error("LINEAR_API_KEY has invalid format");
if (key.length < 30) throw new Error("LINEAR_API_KEY appears truncated");
}
validateConfig();
As of Oct 2025, all new Linear OAuth apps issue refresh tokens. Existing apps must migrate by April 2026.
async function getValidToken(userId: string): Promise<string> {
const stored = await getStoredTokens(userId);
// Refresh if expired or expiring within 5 minutes
if (stored.expiresAt.getTime() - Date.now() < 5 * 60 * 1000) {
const response = await fetch("https://api.linear.app/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
refresh_token: decrypt(stored.refreshToken),
client_id: process.env.LINEAR_CLIENT_ID!,
client_secret: process.env.LINEAR_CLIENT_SECRET!,
}),
});
if (!response.ok) throw new Error(`Token refresh failed: ${response.status}`);
const tokens = await response.json();
// Linear rotates refresh tokens — always store the new one
await storeTokens(userId, {
accessToken: encrypt(tokens.access_token),
refreshToken: encrypt(tokens.refresh_token),
expiresAt: new Date(Date.now() + tokens.expires_in * 1000),
});
return tokens.access_token;
}
return decrypt(stored.accessToken);
}
Step 4: Webhook Signature Verification
Linear signs every webhook with HMAC-SHA256 using the webhook's signing secret. The signature is in the Linear-Signature header.
import crypto from "crypto";
function verifyWebhookSignature(
rawBody: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
// Timing-safe comparison to prevent timing attacks
try {
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
} catch {
return false; // Length mismatch
}
}
// Express middleware — must use raw body parser
app.post("/webhooks/linear", express.raw({ type: "*/*" }), (req, res) => {
const signature = req.headers["linear-signature"] as string;
const rawBody = req.body.toString();
if (!verifyWebhookSignature(rawBody, signature, process.env.LINEAR_WEBHOOK_SECRET!)) {
return res.status(401).json({ error: "Invalid signature" });
}
// Verify webhook timestamp (guard against replay attacks)
const event = JSON.parse(rawBody);
const age = Date.now() - event.webhookTimestamp;
if (age > 60000) {
return res.status(400).json({ error: "Webhook too old" });
}
processEvent(event).catch(console.error);
res.json({ received: true });
});
Step 5: Secret Rotation
// Support multiple keys during rotation period
const apiKeys = [
process.env.LINEAR_API_KEY_NEW,
process.env.LINEAR_API_KEY_OLD,
].filter(Boolean) as string[];
async function getWorkingClient(): Promise<LinearClient> {
for (const apiKey of apiKeys) {
try {
const client = new LinearClient({ apiKey });
await client.viewer; // Verify key works
return client;
} catch {
continue;
}
}
throw new Error("No valid Linear API key found");
}
Security Checklist
API keys in environment variables only (never in code)
.env files in .gitignore
OAuth state parameter validated (CSRF protection)
PKCE used for public/mobile clients
Tokens encrypted at rest in database
Token refresh implemented (mandatory for new apps)
Webhook signatures verified with crypto.timingSafeEqual
Webhook timestamp checked (< 60s age)
HTTPS enforced on all endpoints
Minimal OAuth scopes requested
API keys rotated quarterly
Error Handling
Error
Cause
Solution
Invalid signature
Webhook secret mismatch
Verify LINEAR_WEBHOOK_SECRET in Linear Settings > API > Webhooks
