Agent integration design

curl https://app.reflections.ai/v1/account \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15"

const res = await fetch("https://app.reflections.ai/v1/account", {
  headers: { Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`, "Reflections-Version": "2026-10-15" },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const account = await res.json();

import os, requests

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

// npm install jose
import { createRemoteJWKSet, jwtVerify } from "jose";

// The JWKS is served with max-age=3600, and a key is published 30 days before it signs, so
// refetch for an unknown kid at most once an hour (TLP-TOK-9).
const JWKS = createRemoteJWKSet(new URL("https://app.reflections.ai/.well-known/jwks.json"), {
  cacheMaxAge: 3_600_000,
  cooldownDuration: 3_600_000,
});
// The obligation types of TLP 1.0. Reject a token that carries one you do not handle.
const OBLIGATIONS = new Set([
  "generation_check", "hold_until_release", "draft_watermark", "generation_instructions",
  "disclosure", "attribution", "c2pa_manifest", "no_training", "delete_material", "usage_report",
]);
const ACCOUNT = "acct_7p4r6s9t0wxyhk5zba2q8v1m3n"; // From GET /v1/account
const MODEL = "image-model-3"; // The model this tool runs
const used = new Map<string, number>(); // Use a shared store in production

type Tlp = {
  ver: string;
  decision: string;
  max_generations: number;
  execution: { provider: string; model: string };
  obligations: string[];
};

export async function verifyAuthorization(token: string) {
  const { payload } = await jwtVerify<{ tlp: Tlp }>(token, JWKS, {
    issuer: "https://app.reflections.ai",
    audience: ACCOUNT,
    typ: "tlp-auth+jwt",
    algorithms: ["ES256"],
    clockTolerance: 60,
    maxTokenAge: "15m", // also rejects an iat in the future
    requiredClaims: ["exp", "iat", "jti", "sub"],
  });
  const { tlp } = payload;
  if (tlp.ver.split(".")[0] !== "1") throw new Error("Unsupported protocol version.");
  if (!tlp.obligations.every((type) => OBLIGATIONS.has(type))) throw new Error("Unknown obligation.");
  if (tlp.decision !== "allow") throw new Error("The token is not an allow.");
  if (tlp.execution.model !== MODEL) throw new Error("The token is for a different model.");

  const count = used.get(payload.jti!) ?? 0;
  if (count >= payload.tlp.max_generations) throw new Error("This authorization is used up.");
  used.set(payload.jti!, count + 1);
  return payload; // payload.jti is the check ID
}

import time
import jwt  # pip install "pyjwt[crypto]"

JWKS = jwt.PyJWKClient("https://app.reflections.ai/.well-known/jwks.json", lifespan=3600)
refetch_after = 0.0
# The obligation types of TLP 1.0. Reject a token that carries one you do not handle.
OBLIGATIONS = {
    "generation_check", "hold_until_release", "draft_watermark", "generation_instructions",
    "disclosure", "attribution", "c2pa_manifest", "no_training", "delete_material", "usage_report",
}

def signing_key(token: str):
    """The token's key. Refetches the JWKS for an unknown kid at most once an hour (TLP-TOK-9)."""
    global refetch_after
    kid = jwt.get_unverified_header(token).get("kid")
    keys = {k.key_id: k.key for k in JWKS.get_signing_keys()}
    if kid not in keys and time.time() >= refetch_after:
        refetch_after = time.time() + 3600
        keys = {k.key_id: k.key for k in JWKS.get_signing_keys(refresh=True)}
    if kid not in keys:
        raise PermissionError("unknown_kid")
    return keys[kid]

ACCOUNT = "acct_7p4r6s9t0wxyhk5zba2q8v1m3n"  # From GET /v1/account
MODEL = "image-model-3"  # The model this tool runs
used: dict[str, int] = {}  # Use a shared store in production

def verify_authorization(token: str) -> dict:
    if jwt.get_unverified_header(token).get("typ") != "tlp-auth+jwt":
        raise PermissionError("Not an authorization token.")
    claims = jwt.decode(
        token,
        signing_key(token),
        algorithms=["ES256"],
        audience=ACCOUNT,
        issuer="https://app.reflections.ai",
        leeway=60,
        options={"require": ["exp", "iat", "jti", "sub"]},  # also rejects an iat in the future
    )
    tlp = claims["tlp"]
    if str(tlp["ver"]).split(".")[0] != "1":
        raise PermissionError("Unsupported protocol version.")
    if not set(tlp["obligations"]) <= OBLIGATIONS:
        raise PermissionError("Unknown obligation.")
    if tlp["decision"] != "allow":
        raise PermissionError("The token is not an allow.")
    if tlp["execution"]["model"] != MODEL:
        raise PermissionError("The token is for a different model.")

    count = used.get(claims["jti"], 0)
    if count >= tlp["max_generations"]:
        raise PermissionError("This authorization is used up.")
    used[claims["jti"]] = count + 1
    return claims  # claims["jti"] is the check ID

# CHECK_ID is the verified token's jti. printf is a shell builtin, so the image's base64 is
# not limited by the argument size.
printf '{
  "check": "%s",
  "candidate_index": 0,
  "artifact": { "data": "%s", "sha256": "%s", "media_type": "image/png" },
  "execution": { "provider": "example-image-provider", "model": "image-model-3" }
}' "$CHECK_ID" "$(base64 < output.png | tr -d '\n')" "$(shasum -a 256 output.png | cut -d' ' -f1)" |
curl -sS --fail-with-body https://app.reflections.ai/v1/generations \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: generation-$CHECK_ID-0" \
  -H "Content-Type: application/json" \
  --data-binary @-

import { createHash } from "node:crypto";

async function submitOutput(checkId: string, png: Buffer) {
  const res = await fetch("https://app.reflections.ai/v1/generations", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
      "Reflections-Version": "2026-10-15",
      // One generation per check: if the agent retries the tool call, the first result replays.
      "Idempotency-Key": `generation-${checkId}-0`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      check: checkId,
      candidate_index: 0,
      artifact: {
        data: png.toString("base64"),
        sha256: createHash("sha256").update(png).digest("hex"),
        media_type: "image/png",
      },
      execution: { provider: "example-image-provider", model: MODEL },
    }),
  });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

// const claims = await verifyAuthorization(args.authorization);
// const png = await runModel(args.prompt, args.instructions);
// const generation = await submitOutput(claims.jti!, png);
// if (generation.decision !== "allow") return a tool error with generation.reasons.

import base64, hashlib

def submit_output(check_id: str, png: bytes) -> dict:
    res = requests.post(
        "https://app.reflections.ai/v1/generations",
        headers={
            "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
            "Reflections-Version": "2026-10-15",
            # One generation per check: if the agent retries the tool call, the first result replays.
            "Idempotency-Key": f"generation-{check_id}-0",
        },
        json={
            "check": check_id,
            "candidate_index": 0,
            "artifact": {
                "data": base64.b64encode(png).decode(),
                "sha256": hashlib.sha256(png).hexdigest(),
                "media_type": "image/png",
            },
            "execution": {"provider": "example-image-provider", "model": MODEL},
        },
    )
    res.raise_for_status()
    return res.json()

# claims = verify_authorization(args["authorization"])
# png = run_model(args["prompt"], args["instructions"])
# generation = submit_output(claims["jti"], png)
# if generation["decision"] != "allow": return a tool error with generation["reasons"].