Build an integration (for coding agents)

// node ap-client.mjs — credentials come from the environment, never from the repository
import crypto from "node:crypto";
import http from "node:http";

const ISSUER = "https://www.agentplanners.com";
const API = ISSUER + "/api/v1";
const CLIENT_ID = process.env.AGENTPLANNERS_CLIENT_ID; // apc_… of your Public app
const REDIRECT = "http://127.0.0.1:8787/callback";     // registered on the app, exactly
const b64url = (buf) => buf.toString("base64url");

// 1. PKCE + state, fresh for every sign-in
const verifier = b64url(crypto.randomBytes(32));
const challenge = b64url(crypto.createHash("sha256").update(verifier).digest());
const state = b64url(crypto.randomBytes(16));
const authorize = new URL("/oauth/authorize", ISSUER);
authorize.search = new URLSearchParams({
  response_type: "code", client_id: CLIENT_ID, redirect_uri: REDIRECT,
  code_challenge: challenge, code_challenge_method: "S256",
  scope: "accounts:read tools:read tools:write", state, resource: API,
}).toString();
console.log("Open this URL and approve:", authorize.href);

// 2. The redirect back: check state and iss before using the code
const code = await new Promise((resolve, reject) => {
  const server = http.createServer((req, res) => {
    const q = new URL(req.url, REDIRECT).searchParams;
    res.end("You can close this tab.");
    server.close();
    if (q.get("state") !== state || q.get("iss") !== ISSUER) return reject(new Error("state or iss mismatch"));
    if (q.get("error")) return reject(new Error(q.get("error")));
    resolve(q.get("code"));
  }).listen(8787, "127.0.0.1");
});

async function token(params) {
  const r = await fetch(ISSUER + "/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ client_id: CLIENT_ID, ...params }),
  });
  const body = await r.json();
  if (!r.ok) throw new Error(r.status + " " + body.error + ": " + (body.error_description || ""));
  return body; // { access_token, token_type, expires_in, refresh_token, scope }
}
let tok = await token({ grant_type: "authorization_code", code, redirect_uri: REDIRECT, code_verifier: verifier, resource: API });
await saveRefreshToken(tok.refresh_token); // every refresh replaces it — keep only the newest

// 3. One helper: refresh once on 401, wait out 429 / 503 once, same Idempotency-Key on the retry
async function call(method, path, body, idempotencyKey, retried = false) {
  const headers = { Authorization: "Bearer " + tok.access_token };
  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  const r = await fetch(API + path, { method, headers, body: body ? JSON.stringify(body) : undefined });
  if (!retried && r.status === 401) {
    tok = await token({ grant_type: "refresh_token", refresh_token: tok.refresh_token });
    await saveRefreshToken(tok.refresh_token);
    return call(method, path, body, idempotencyKey, true);
  }
  if (!retried && (r.status === 429 || r.status === 503)) {
    await new Promise((ok) => setTimeout(ok, 1000 * Number(r.headers.get("Retry-After") || 30)));
    return call(method, path, body, idempotencyKey, true);
  }
  return { status: r.status, body: await r.json() };
}

// 4. Discover, read, write, poll
const caps = (await call("GET", "/capabilities")).body;
if (!caps.tools.enabled) throw new Error("Tools are off: " + caps.tools.notEnabledBecause);
const accounts = (await call("GET", "/accounts")).body.accounts;
const gads = accounts.find((a) => a.provider === "google_ads"); // match the account the user named, not the first one
const health = await call("POST", "/tools/google_ads__get_account_health", { accountId: gads.id });
console.log(health.status, health.body.result);

const write = await call("POST", "/tools/google_ads__mutate_campaign", {
  accountId: gads.id,
  campaignResourceName: "customers/1234567890/campaigns/111222333",
  finalUrlSuffix: "utm_source=google&utm_medium=cpc",
}, "utm-suffix-campaign-111222333-v1");
if (write.status === 202) {
  let decision;
  do {
    await new Promise((ok) => setTimeout(ok, 5000));
    decision = (await call("GET", "/requests/" + encodeURIComponent(write.body.requestId))).body.result;
  } while (decision.status === "pending_approval" || decision.status === "approved");
  console.log("decided:", decision.status); // executed | failed | rejected | expired
}

async function saveRefreshToken(rt) { /* write it to your secret store — not a file in the repository */ }

# python ap_client.py — credentials come from the environment, never from the repository
import base64, hashlib, os, secrets, time, urllib.parse
import requests

ISSUER = "https://www.agentplanners.com"
API = ISSUER + "/api/v1"
CLIENT_ID = os.environ["AGENTPLANNERS_CLIENT_ID"]   # apc_... of your Public app
REDIRECT = "http://127.0.0.1:8787/callback"          # registered on the app, exactly

def b64url(b): return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
def save_refresh_token(rt): pass  # write it to your secret store, not a file in the repository

verifier = b64url(secrets.token_bytes(32))
challenge = b64url(hashlib.sha256(verifier.encode()).digest())
state = b64url(secrets.token_bytes(16))
print("Open this URL and approve:", ISSUER + "/oauth/authorize?" + urllib.parse.urlencode({
    "response_type": "code", "client_id": CLIENT_ID, "redirect_uri": REDIRECT,
    "code_challenge": challenge, "code_challenge_method": "S256",
    "scope": "accounts:read tools:read tools:write", "state": state, "resource": API}))
back = urllib.parse.parse_qs(urllib.parse.urlparse(input("Paste the URL you were sent back to: ")).query)
if back.get("state") != [state] or back.get("iss") != [ISSUER]: raise SystemExit("state or iss mismatch")
if "error" in back: raise SystemExit(back["error"][0])

def token(**params):
    r = requests.post(ISSUER + "/oauth/token", data={"client_id": CLIENT_ID, **params}, timeout=30)
    body = r.json()
    if r.status_code != 200: raise RuntimeError(f"{r.status_code} {body.get('error')}: {body.get('error_description', '')}")
    return body

tok = token(grant_type="authorization_code", code=back["code"][0], redirect_uri=REDIRECT, code_verifier=verifier, resource=API)
save_refresh_token(tok["refresh_token"])  # every refresh replaces it: keep only the newest

def call(method, path, json=None, idempotency_key=None, retried=False):
    global tok
    headers = {"Authorization": "Bearer " + tok["access_token"]}
    if idempotency_key: headers["Idempotency-Key"] = idempotency_key
    r = requests.request(method, API + path, json=json, headers=headers, timeout=60)
    if not retried and r.status_code == 401:
        tok = token(grant_type="refresh_token", refresh_token=tok["refresh_token"])
        save_refresh_token(tok["refresh_token"])
        return call(method, path, json, idempotency_key, True)
    if not retried and r.status_code in (429, 503):
        time.sleep(int(r.headers.get("Retry-After", "30")))
        return call(method, path, json, idempotency_key, True)
    return r.status_code, r.json()

_, caps = call("GET", "/capabilities")
if not caps["tools"]["enabled"]: raise SystemExit("Tools are off: " + caps["tools"]["notEnabledBecause"])
_, accts = call("GET", "/accounts")
gads = next(a for a in accts["accounts"] if a["provider"] == "google_ads")  # match the account the user named
status, health = call("POST", "/tools/google_ads__get_account_health", {"accountId": gads["id"]})
print(status, health.get("result"))

status, write = call("POST", "/tools/google_ads__mutate_campaign", {
    "accountId": gads["id"],
    "campaignResourceName": "customers/1234567890/campaigns/111222333",
    "finalUrlSuffix": "utm_source=google&utm_medium=cpc",
}, idempotency_key="utm-suffix-campaign-111222333-v1")
if status == 202:
    while True:
        time.sleep(5)
        _, r = call("GET", "/requests/" + urllib.parse.quote(write["requestId"]))
        if r["result"]["status"] not in ("pending_approval", "approved"): break
    print("decided:", r["result"]["status"])  # executed | failed | rejected | expired