Agent-initiated, human-approved subscriptions

Agent (no key)                 Cold Leads                         Human owner              Stripe
     |                              |                                   |                     |
     | POST /api/agent/provision    |                                   |                     |
     | owner_email, agent_id,       |                                   |                     |
     | callback_url (optional)      |                                   |                     |
     |----------------------------->| pending account, disabled key,    |                     |
     |                              | Checkout session (24 h) --------------------------------->|
     |<-----------------------------| checkout_url, session_id,         |                     |
     |                              | claim_token (shown once)          |                     |
     | shows checkout_url --------------------------------------------->|                     |
     |                              |                                   | reviews plan, pays->|
     |                              |<-------------------------------------- payment webhook --|
     |                              | activates account and key,        |                     |
     |                              | e-mails the owner a sign-in link ->|                     |
     |<-- signed callback (optional, no secrets) -----------------------|                     |
     | GET /api/agent/status        |                                   |                     |
     | ?session_id=...              |                                   |                     |
     | X-Claim-Token: clt_...       |                                   |                     |
     |----------------------------->|                                   |                     |
     |<-----------------------------| status active + api_key           |                     |
     |                              | (first call only)                 |                     |

curl -s https://coldleads.app/api/agent/provision \
  -H "Content-Type: application/json" \
  -d '{
    "owner_email": "owner@example.com",
    "agent_id": "Acme Research Agent",
    "callback_url": "https://agent.example.com/hooks/coldleads"
  }'

{
  "status": "payment_required",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_…",
  "session_id": "cs_live_…",
  "provision_id": "prov_…",
  "claim_token": "clt_…",
  "expires_at": "2026-10-01T09:30:00.000Z",
  "plan": { "id": "business", "name": "Business", "price": "$99", "amount": 99, "currency": "usd", "interval": "month", "api": true },
  "status_url": "https://coldleads.app/api/agent/status?session_id=cs_live_…",
  "instructions_for_agent": "Show the human owner (owner@example.com) this payment link and let them decide: … Do not open, pay or forward the link yourself. Keep claim_token secret (it is shown only now). …"
}

{
  "session_id": "cs_live_…",
  "plan": "business",
  "status": "active",
  "activated_at": "2026-09-30T10:02:11.000Z",
  "api_key_prefix": "sk_…9f3c",
  "mcp_url": "https://coldleads.app/api/mcp",
  "api_base": "https://coldleads.app/api/v1",
  "api_key": "sk_…",
  "message": "This is the only time the key is shown. Store it as COLDLEADS_API_KEY; send it as Authorization: Bearer <key>."
}

# pip install httpx
import os
import time

import httpx

BASE = "https://coldleads.app"
SESSION_ID = os.environ["COLDLEADS_SESSION_ID"]    # session_id from the provision response
CLAIM_TOKEN = os.environ["COLDLEADS_CLAIM_TOKEN"]  # claim_token (clt_...), shown only once


def save_key(key: str) -> None:
    path = os.path.expanduser("~/.coldleads_api_key")  # or your secret manager
    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    with os.fdopen(fd, "w") as f:
        f.write(key)


while True:
    r = httpx.get(f"{BASE}/api/agent/status", params={"session_id": SESSION_ID},
                  headers={"X-Claim-Token": CLAIM_TOKEN}, timeout=30)
    if r.status_code == 429:  # 120 status requests per minute per IP
        time.sleep(60)
        continue
    r.raise_for_status()
    s = r.json()
    if s["status"] == "active":
        if "api_key" not in s:
            raise SystemExit("The key was already collected; the owner can rotate it in Settings -> API keys.")
        save_key(s["api_key"])
        print("API key saved; prefix", s["api_key_prefix"])
        break
    if s["status"] in ("expired", "suspended"):
        raise SystemExit(s.get("message", s["status"]))
    time.sleep(20)  # pending_payment: poll every 15-30 seconds

// npm install express
import express from "express";
import { createHash, createHmac, timingSafeEqual } from "node:crypto";

const CLAIM_TOKEN = process.env.COLDLEADS_CLAIM_TOKEN; // clt_... from the provision response

// X-Coldleads-Signature: sha256=<hex HMAC-SHA256 of the raw body>, key = SHA-256 hex digest of the claim token
function validSignature(rawBody, header, claimToken) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string" || !header.startsWith("sha256=")) return false;
  const key = createHash("sha256").update(claimToken).digest("hex");
  const expected = createHmac("sha256", key).update(rawBody).digest();
  const given = Buffer.from(header.slice("sha256=".length), "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

const app = express();
app.post("/hooks/coldleads", express.raw({ type: "application/json" }), (req, res) => {
  if (!validSignature(req.body, req.get("x-coldleads-signature"), CLAIM_TOKEN)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(204); // answer fast: Cold Leads waits 5 seconds and does not retry
  if (event.event === "coldleads.account.activated") {
    // the callback carries no key: collect it now with GET /api/agent/status + X-Claim-Token
    console.log("owner paid, session", event.session_id);
  }
});
app.listen(3000);

# pip install flask
import hashlib
import hmac
import json
import os

from flask import Flask, request

CLAIM_TOKEN = os.environ["COLDLEADS_CLAIM_TOKEN"]  # clt_... from the provision response
app = Flask(__name__)


def valid_signature(raw_body: bytes, header, claim_token: str) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    key = hashlib.sha256(claim_token.encode()).hexdigest().encode()
    expected = hmac.new(key, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header[len("sha256="):])


@app.post("/hooks/coldleads")
def coldleads_callback():
    raw = request.get_data()  # the raw bytes, before any JSON parsing
    if not valid_signature(raw, request.headers.get("X-Coldleads-Signature"), CLAIM_TOKEN):
        return "", 401
    event = json.loads(raw)
    if event.get("event") == "coldleads.account.activated":
        # the callback carries no key: collect it with GET /api/agent/status + X-Claim-Token
        print("owner paid, session", event["session_id"])
    return "", 204