Authentication

import { createHash, randomBytes } from "node:crypto";

const account = await fetch("https://app.reflections.ai/v1/account", {
  headers: {
    Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
    "Reflections-Version": "2026-10-15",
  },
}).then((r) => r.json());

const codeVerifier = randomBytes(32).toString("base64url");
const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
const state = randomBytes(16).toString("base64url");

const url = new URL("https://app.reflections.ai/oauth/authorize");
url.search = new URLSearchParams({
  response_type: "code",
  client_id: account.platform.client_id,
  redirect_uri: "https://northlight.example/oauth/reflections/callback",
  scope: "files:write checks:write generations:write usage:write",
  state,
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
}).toString();
// Store codeVerifier and state with the user's session, then redirect to url.

import base64, hashlib, os, secrets, requests
from urllib.parse import urlencode

account = requests.get(
    "https://app.reflections.ai/v1/account",
    headers={
        "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
        "Reflections-Version": "2026-10-15",
    },
).json()

code_verifier = secrets.token_urlsafe(32)
code_challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest())
    .rstrip(b"=")
    .decode()
)
state = secrets.token_urlsafe(16)

url = "https://app.reflections.ai/oauth/authorize?" + urlencode({
    "response_type": "code",
    "client_id": account["platform"]["client_id"],
    "redirect_uri": "https://northlight.example/oauth/reflections/callback",
    "scope": "files:write checks:write generations:write usage:write",
    "state": state,
    "code_challenge": code_challenge,
    "code_challenge_method": "S256",
})
# Store code_verifier and state with the user's session, then redirect to url.

curl https://app.reflections.ai/v1/connections \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: connection-$STATE" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "ac_Jf3k9QmZ2vX8pT4wR7nY1bL6",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
    "redirect_uri": "https://northlight.example/oauth/reflections/callback"
  }'

// In your redirect handler, after checking state. codeVerifier is from the user's session.
export async function createConnection(code: string, codeVerifier: string, state: string) {
  const res = await fetch("https://app.reflections.ai/v1/connections", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
      "Reflections-Version": "2026-10-15",
      "Idempotency-Key": `connection-${state}`, // A retry redeems the code once.
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      code,
      code_verifier: codeVerifier,
      redirect_uri: "https://northlight.example/oauth/reflections/callback",
    }),
  });
  if (!res.ok) throw new Error(`Create connection failed: ${res.status} ${await res.text()}`);
  return res.json(); // The connection; its `licensee` is the account you act for.
}

def create_connection(code, code_verifier, state):
    """In your redirect handler, after checking state. code_verifier is from the user's session."""
    res = requests.post(
        "https://app.reflections.ai/v1/connections",
        headers={
            "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
            "Reflections-Version": "2026-10-15",
            "Idempotency-Key": f"connection-{state}",  # A retry redeems the code once.
        },
        json={
            "code": code,
            "code_verifier": code_verifier,
            "redirect_uri": "https://northlight.example/oauth/reflections/callback",
        },
        timeout=10,
    )
    res.raise_for_status()
    return res.json()  # The connection; its "licensee" is the account you act for.