poe-oauth

OAuth client and auth verification for the Poe API.

OAuth

PKCE-based OAuth flow with local callback server:

import { createOAuthClient } from "poe-oauth";

const client = createOAuthClient({
  clientId: "your-client-id",
  openBrowser: async (url) => {
    /* open url in browser */
  },
  readLine: async () => {
    /* read manual paste from terminal */
  }
});
// Defaults to https://poe.com/oauth/authorize and https://api.poe.com/token
// Override with authorizationEndpoint / tokenEndpoint if needed

const authorization = await client.authorize();
// authorization.authorizationUrl — URL to open in browser
const result = await authorization.waitForResult();
// result.apiKey, result.expiresIn

Caller-managed callback

Applications that own their HTTP callback route can compose the same authorization and exchange primitives without starting a listener, opening a browser, or reading terminal input:

import crypto from "node:crypto";
import {
  createOAuthAuthorizationUrl,
  exchangeOAuthCode,
  generateCodeChallenge,
  generateCodeVerifier,
  validateOAuthAuthorizationCallback
} from "poe-oauth";

const clientId = "your-client-id";
const redirectUri = "https://app.example.com/oauth/callback";
const state = crypto.randomBytes(32).toString("base64url");
const codeVerifier = generateCodeVerifier();

const authorizationUrl = createOAuthAuthorizationUrl({
  clientId,
  redirectUri,
  state,
  codeChallenge: generateCodeChallenge(codeVerifier)
});

// Redirect the user to authorizationUrl. In your callback route:
const code = validateOAuthAuthorizationCallback({
  callbackUrl: new URL(request.url, redirectUri),
  expectedState: state
});
const result = await exchangeOAuthCode({
  clientId,
  redirectUri,
  code,
  codeVerifier
});
// result.apiKey, result.expiresIn

Keep state and codeVerifier private, bind them to the initiating user session, and discard them after one callback attempt. validateOAuthAuthorizationCallback rejects missing or mismatched state before returning an authorization code.

Landing page

Customize the browser page shown after successful authorization:

const client = createOAuthClient({
  clientId: "your-client-id",
  landingPage: {
    title: "All set!",
    body: "You can close this tab and return to your IDE."
  }
});

Defaults to "Connected to Poe" / "You can close this tab and return to your terminal." when omitted.

Configuration Options

• clientId: Poe OAuth client id.
• authorizationEndpoint: optional authorization endpoint override.
• tokenEndpoint: optional token endpoint override.
• openBrowser: callback used to open the authorization URL.
• readLine: callback used for manual code-paste fallback.
• landingPage: success page copy for the local callback server.

The caller-managed helpers accept optional authorizationEndpoint, tokenEndpoint, and fetch overrides. Redirect URIs may use hosted HTTPS callbacks or local HTTP loopback callbacks.

Environment Variables

This package does not read public environment variables.

Check auth

Verify an API key and fetch the associated identity:

import { checkAuth } from "poe-oauth";

const identity = await checkAuth({ apiKey: "sk-poe-..." });
// { email: "[email protected]", balance: 1500 } | null