API reference

Core API

The headless engine. Every function takes an optional TokenStore; the default is an encrypted file store.

imports

import {
  login,
  startLogin,
  startDeviceLogin,
  logout,
  getSession,
  refresh,
  createClient
} from "loginwithchatgpt";

Functions

  • login() — loopback OAuth flow (desktop/local), stores tokens.
  • startDeviceLogin() — device-code flow for web/headless; returns { userCode, verificationUrl, wait }.
  • startLogin() — headless paste flow for SSH/CI; returns { url, complete }.
  • getSession() — current session, or null.
  • refresh() — force a token refresh.
  • logout() — clear stored tokens.
  • createClient() — a client with respond(prompt) and stream(prompt).

Login flows

  • - Loopback — auto-captures the redirect on the user's machine. Best for desktop/CLI.
  • - Device code — shows a short code the user enters on an OpenAI page. Works on web/headless.
  • - Headless paste — user copies the code from the redirect URL. Fallback for SSH/containers.

Token storage

Tokens are encrypted at rest (AES-256-GCM) with a key kept in the OS keychain where available. Storage is pluggable through the TokenStore interface.

custom store

import { createClient, type TokenStore } from "loginwithchatgpt";

const myStore: TokenStore = { load, save, clear };
const client = createClient(myStore);

Entry points

  • loginwithchatgpt — engine (Node).
  • loginwithchatgpt/react — button + hook (browser).
  • loginwithchatgpt/next — App Router handlers (Node).

Back to the Quickstart.