@coopah/copilot-auth

GitHub Copilot OAuth device flow + OpenAI-compatible client config with auto-refreshing tokens.

Install

npm install @coopah/copilot-auth

Prerequisites

An active GitHub Copilot subscription
Node.js 18+

Quick Start

1. Implement token storage

Store the GitHub OAuth token however you like — database, file, env var, etc.

import type { TokenStorage } from '@coopah/copilot-auth';

const storage: TokenStorage = {
  async getToken() {
    return process.env.GITHUB_TOKEN ?? null;
  },
  async setToken(token) {
    process.env.GITHUB_TOKEN = token;
  },
};

2. Login and use

import { CopilotAuth } from '@coopah/copilot-auth';
import OpenAI from 'openai';

const auth = new CopilotAuth({ storage });

// One call — prints the code/URL to console, polls until authorized
await auth.login();

// Get an auto-refreshing OpenAI-compatible config
const config = await auth.getOpenAIClientConfig();
const openai = new OpenAI(config);

const completion = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

login() skips the flow if a token already exists. getSessionCredentials() caches and auto-refreshes the Copilot session token.

You can also use startDeviceFlow() and pollDeviceFlow() directly if you need lower-level control.

Refreshing credentials

The session token expires periodically. Use getCredentialsIfChanged() to rebuild your client only when needed:

const newCreds = await auth.getCredentialsIfChanged();
if (newCreds) {
  openai = new OpenAI(await auth.getOpenAIClientConfig());
}

Express Integration

Mount two POST endpoints for the device flow on any Express router:

import express from 'express';
import { mountCopilotRoutes } from '@coopah/copilot-auth/express';

const app = express();
app.use(express.json());

const router = express.Router();
mountCopilotRoutes({ router, storage });
app.use('/api', router);

// Exposes:
//   POST /api/copilot/device-code  → starts the device flow
//   POST /api/copilot/device-poll  → polls for completion (body: { device_code })

app.listen(3000);

mountCopilotRoutes returns the CopilotAuth instance, so you can reuse it:

const auth = mountCopilotRoutes({ router, storage });
const config = await auth.getOpenAIClientConfig();

API Reference