Linear OAuth 2.0 Refresh Token Implementation Summary

Issue: PLT-1189
PR: #473
Status: ✅ Complete - Ready for Review
Branch: cursor/PLT-1189-linear-oauth-refresh-tokens-5916

Overview

Successfully implemented OAuth 2.0 with refresh token support for Linear integrations to meet Linear’s April 1, 2026 deadline for deprecating long-lived access tokens.

What Was Built

1. OAuth Flow Implementation

Authorization Endpoint (src/app/api/brainforge/linear/oauth/authorize/route.ts)

Initiates OAuth flow
Redirects to Linear for authorization
Handles state parameter for post-auth redirect

Callback Endpoint (src/app/api/brainforge/linear/oauth/callback/route.ts)

Receives authorization code from Linear
Exchanges code for access and refresh tokens
Stores tokens securely in Supabase
Shows success/error pages to user

Migration Endpoint (src/app/api/brainforge/linear/oauth/migrate/route.ts)

Attempts to migrate old tokens (if Linear supports it)
Provides fallback to re-authorization
Shows helpful error messages and guidance

2. Token Management System

Token Manager (src/lib/linearOAuth.ts)

Stores and retrieves tokens from Supabase
Automatic token expiry checking
Automatic token refresh when needed
Fallback to static API keys for backward compatibility
In-memory caching for performance

Updated Linear API Client (src/lib/linearApiServer.ts)

Now uses getLinearAccessToken() for all requests
Automatically refreshes expired tokens
Gracefully falls back to static keys if OAuth not configured

3. Database Schema

Supabase Migration (supabase/migrations/007_create_linear_oauth_tokens_table.sql)

Creates linear_oauth_tokens table
Stores access tokens, refresh tokens, and expiry
Includes indexes for performance
Auto-updates updated_at timestamp

4. Documentation

Migration Guide (docs/LINEAR_OAUTH_MIGRATION.md)

Comprehensive overview of the migration
Step-by-step instructions
OAuth flow diagrams
API reference
Troubleshooting guide
Security best practices

Setup Guide (scripts/linear-oauth-setup.md)

Quick setup checklist
Environment configuration
Database setup
Testing procedures
Deployment steps

Test Suite (tests/linearOAuth.test.ts)

Automated smoke tests
Manual testing checklist
Environment validation

5. Environment Configuration

Updated .env.example

Added OAuth client ID and secret
Marked old API keys as deprecated
Clear migration instructions

Technical Details

OAuth 2.0 Flow

┌─────────┐                     ┌────────┐                     ┌──────────┐
│ Browser │                     │ Server │                     │  Linear  │
└────┬────┘                     └───┬────┘                     └────┬─────┘
     │                              │                               │
     │ 1. GET /oauth/authorize      │                               │
     ├─────────────────────────────>│                               │
     │                              │                               │
     │                              │ 2. Redirect to Linear         │
     │<─────────────────────────────┤                               │
     │                                                              │
     │ 3. Redirect to linear.app/oauth/authorize                    │
     ├─────────────────────────────────────────────────────────────>│
     │                                                              │
     │ 4. User authorizes                                           │
     │                                                              │
     │ 5. Redirect back with code                                   │
     │<─────────────────────────────────────────────────────────────┤
     │                              │                               │
     │ 6. GET /oauth/callback?code=...                              │
     ├─────────────────────────────>│                               │
     │                              │                               │
     │                              │ 7. POST /oauth/token         │
     │                              │    (exchange code for tokens) │
     │                              ├──────────────────────────────>│
     │                              │                               │
     │                              │ 8. Return tokens              │
     │                              │<──────────────────────────────┤
     │                              │                               │
     │                              │ 9. Store in Supabase          │
     │                              │                               │
     │ 10. Success page             │                               │
     │<─────────────────────────────┤                               │
     │                              │                               │

Token Refresh Flow

┌────────┐                     ┌──────────┐
│  API   │                     │  Linear  │
└───┬────┘                     └────┬─────┘
    │                               │
    │ 1. linearRequest()            │
    │    (check if token expired)   │
    │                               │
    │ 2. Token expired?             │
    │    POST /oauth/token          │
    │    grant_type=refresh_token   │
    ├──────────────────────────────>│
    │                               │
    │ 3. New access token           │
    │<──────────────────────────────┤
    │                               │
    │ 4. Store in Supabase          │
    │                               │
    │ 5. Make GraphQL request       │
    │    with new token             │
    ├──────────────────────────────>│
    │                               │
    │ 6. API response               │
    │<──────────────────────────────┤
    │                               │

Key Features

✅ Automatic Token Refresh - No manual intervention needed
✅ Secure Storage - Tokens stored in Supabase, not in code
✅ Backward Compatible - Falls back to static API keys
✅ Production Ready - Error handling and logging
✅ Well Documented - Comprehensive guides and examples
✅ Type Safe - Full TypeScript support
✅ Tested - Linting and type checking pass

Migration Steps for Team

For Development

Update Linear OAuth App
- Go to https://linear.app/brainforge/settings/api/applications
- Select the OAuth app
- Enable “Refresh Tokens”
- Add callback URL: http://localhost:3000/api/brainforge/linear/oauth/callback

Set Environment Variables

BRAINFORGE_PLATFORM_LINEAR_APP_CLIENT_ID=your_client_id
BRAINFORGE_PLATFORM_LINEAR_APP_CLIENT_SECRET=your_client_secret

Apply Database Migration

cd apps/platform
# Run migration 007_create_linear_oauth_tokens_table.sql in Supabase

Authorize Application
- Visit http://localhost:3000/api/brainforge/linear/oauth/authorize
- Complete OAuth flow
Verify
```
SELECT * FROM linear_oauth_tokens;
```

For Production

Same steps as development, but:

Use production Linear OAuth app
Use production callback URL: https://your-domain.com/api/brainforge/linear/oauth/callback
Apply migration to production Supabase
Set production environment variables

Affected Applications

Must be migrated before April 1, 2026:

Polytomic Data Extraction
- Used for ETL workflows
- Requires read/write access to Linear
Brainforge AI Automations
- Used for AI-powered workflows
- Requires read/write access to Linear

Files Changed

New Files (8)

src/lib/linearOAuth.ts
src/app/api/brainforge/linear/oauth/authorize/route.ts
src/app/api/brainforge/linear/oauth/callback/route.ts
src/app/api/brainforge/linear/oauth/migrate/route.ts
supabase/migrations/007_create_linear_oauth_tokens_table.sql
docs/LINEAR_OAUTH_MIGRATION.md
scripts/linear-oauth-setup.md
tests/linearOAuth.test.ts

Modified Files (2)

src/lib/linearApiServer.ts
.env.example

Total: +1,536 insertions, -14 deletions

Commits

feat: implement Linear OAuth 2.0 refresh token support (PLT-1189)
- Core OAuth implementation
- Token management
- Database migration
docs: add Linear OAuth setup guide and tests (PLT-1189)
- Documentation
- Test suite
- Setup guides

Next Steps

Code Review - Review PR #473
Testing - Manual testing of OAuth flow
Deploy - Merge and deploy to staging
Production Migration - Apply to production
Monitor - Watch for token refresh issues
Deprecate Old Tokens - Remove static API keys after successful migration

Timeline

✅ Now: Implementation complete, PR ready for review
📅 Next: Code review and testing
📅 April 1, 2026: Deadline for migration (plenty of time!)

Resources

PR: https://github.com/brainforge-ai/brainforge-platform/pull/473
Linear Issue: https://linear.app/brainforge/issue/PLT-1189
Linear OAuth Docs: https://linear.app/developers/oauth-2-0-authentication
Migration Guide: apps/platform/docs/LINEAR_OAUTH_MIGRATION.md
Setup Guide: apps/platform/scripts/linear-oauth-setup.md

Questions or Issues?

Contact the team or refer to the comprehensive documentation in:

docs/LINEAR_OAUTH_MIGRATION.md - Detailed migration guide
scripts/linear-oauth-setup.md - Quick setup instructions
tests/linearOAuth.test.ts - Testing guidelines

Status: ✅ Ready for Review
Confidence: High - Implementation follows OAuth 2.0 standards and Linear’s best practices
Risk: Low - Backward compatible, well-documented, includes fallbacks

Brainforge Knowledge

Explorer

LINEAR_OAUTH_IMPLEMENTATION_SUMMARY