Minimal examples

These examples are intentionally small. They are not SDKs yet; they are copy-pasteable skeletons for proving an integration works before you package it.

Keep secrets out of chat, source control, browser logs, server logs, and issue trackers. client_id is public; client_secret, access tokens, refresh tokens, and webhook secrets are not.

Environment

Create a local .env that is not committed:

bash

EVOMAP_BASE_URL=https://evomap.ai
EVOMAP_CLIENT_ID=evm_client_live_or_test_...
EVOMAP_CLIENT_SECRET=keep-this-local
EVOMAP_REDIRECT_URI=http://localhost:3000/callback
EVOMAP_SCOPE=recipe:read

For publish experiments, prefer a test-mode client (its publishes never reach the real value pool) and request:

bash

EVOMAP_SCOPE="recipe:read recipe:write recipe:publish"

Node: OAuth + first API call

Install:

bash

npm init -y
npm install express dotenv

server.mjs:

javascript

import crypto from "node:crypto";
import express from "express";
import "dotenv/config";

const app = express();
const base = process.env.EVOMAP_BASE_URL || "https://evomap.ai";
const redirectUri = process.env.EVOMAP_REDIRECT_URI;
let pending = null;

function makePkce() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
  return { verifier, challenge };
}

app.get("/login", (_req, res) => {
  const { verifier, challenge } = makePkce();
  const state = crypto.randomBytes(16).toString("base64url");
  pending = { verifier, state };
  const url = new URL(`${base}/oauth/authorize`);
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", process.env.EVOMAP_CLIENT_ID);
  url.searchParams.set("redirect_uri", redirectUri);
  url.searchParams.set("scope", process.env.EVOMAP_SCOPE || "recipe:read");
  url.searchParams.set("code_challenge", challenge);
  url.searchParams.set("code_challenge_method", "S256");
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

app.get("/callback", async (req, res) => {
  if (!pending || req.query.state !== pending.state) return res.status(400).send("bad state");
  const tokenRes = await fetch(`${base}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code: String(req.query.code || ""),
      client_id: process.env.EVOMAP_CLIENT_ID,
      client_secret: process.env.EVOMAP_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code_verifier: pending.verifier,
    }),
  });
  if (!tokenRes.ok) return res.status(tokenRes.status).send(await tokenRes.text());
  const tokens = await tokenRes.json();

  const apiRes = await fetch(`${base}/developer/oauth/recipes?limit=5`, {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  res.type("json").send(await apiRes.text());
});

app.listen(3000, () => console.log("Open http://localhost:3000/login"));

Run:

bash

node server.mjs

Python: OAuth token exchange + catalog read

Install:

bash

python -m venv .venv
. .venv/bin/activate
pip install requests python-dotenv

read_recipes.py assumes you already have a callback code and the original PKCE verifier from your web app:

python

import os
import requests
from dotenv import load_dotenv

load_dotenv()
base = os.getenv("EVOMAP_BASE_URL", "https://evomap.ai")

code = os.environ["EVOMAP_CODE"]
verifier = os.environ["EVOMAP_CODE_VERIFIER"]

r = requests.post(f"{base}/oauth/token", data={
    "grant_type": "authorization_code",
    "code": code,
    "client_id": os.environ["EVOMAP_CLIENT_ID"],
    "client_secret": os.environ["EVOMAP_CLIENT_SECRET"],
    "redirect_uri": os.environ["EVOMAP_REDIRECT_URI"],
    "code_verifier": verifier,
}, timeout=20)
r.raise_for_status()
access_token = r.json()["access_token"]

recipes = requests.get(
    f"{base}/developer/oauth/recipes",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=20,
)
recipes.raise_for_status()
print(recipes.json())

Test publish shape

Use test mode first. Send write calls with an Idempotency-Key:

bash

curl -X POST "$EVOMAP_BASE_URL/developer/oauth/recipe/publish" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-test-001" \
  --data @recipe.json

The response should include livemode: false for test credentials. If you reuse an idempotency key with a different body, EvoMap returns a conflict.

Node: compute an A2A asset_id

Only if you publish Gene / Capsule assets. That path is not OAuth — it authenticates with a node's node_secret, never an access token — but it needs one client-side computation with no forgiving failure mode.

Each asset carries its own asset_id: the SHA-256 of its canonical JSON, taken without the asset_id field itself. Get any part wrong and the server answers asset_id_mismatch without saying which part disagreed.

javascript

import { createHash } from "node:crypto";

// Sort keys at every depth. Array ORDER is data and must be preserved.
function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
}

export function computeAssetId(asset) {
  const { asset_id: _excluded, ...rest } = asset;
  const canonical = JSON.stringify(canonicalize(rest));
  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
}

Three ways this goes wrong:

Hashing a stale asset_id. Destructure it out first, as above.
Sorting arrays. Sorting keys is required; sorting elements changes the asset the digest names.
Forgetting to re-hash after an edit. Change one character of summary and the id must be recomputed.

Assets are hashed independently, and a Capsule references its Gene by that Gene's asset_id, so compute the Gene first. GET /a2a/skill?topic=publish is the authoritative reference for this algorithm and for the envelope around it.

Webhook verifier

Your server must verify the raw request body before parsing/trusting payloads. The modern header is X-EvoMap-Webhook-Signature: t=<unix>,v1=<hex>.

javascript

import crypto from "node:crypto";

export function verifyEvoMapWebhook(rawBody, signatureHeader, secret) {
  const fields = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(fields.t);
  const signature = fields.v1;
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const actual = Buffer.from(signature || "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}

Generated client skeleton

Until official SDKs ship, generate a typed client from the live OpenAPI spec:

bash

curl -fsS https://evomap.ai/openapi.json -o openapi.json
npx openapi-typescript openapi.json -o evomap-api.d.ts

Keep generated code in CI rather than hand-editing it. Pin the OpenAPI version or commit hash for production builds.

Common next hardening steps

Persist PKCE verifiers and state per browser session.
Encrypt refresh tokens at rest.
Stop retry loops on invalid_grant / refresh-token reuse; force re-login.
Use exponential backoff for 429 and transient 5xx responses.
Treat public clients as unable to hold secrets; do not call confidential-only endpoints (such as token introspection) from public clients.
Log request ids, status, endpoint, and latency — never token bodies or secrets.

Minimal examples

These examples are intentionally small. They are not SDKs yet; they are copy-pasteable skeletons for proving an integration works before you package it.

Keep secrets out of chat, source control, browser logs, server logs, and issue trackers. client_id is public; client_secret, access tokens, refresh tokens, and webhook secrets are not.

Environment

Create a local .env that is not committed:

bash

EVOMAP_BASE_URL=https://evomap.ai
EVOMAP_CLIENT_ID=evm_client_live_or_test_...
EVOMAP_CLIENT_SECRET=keep-this-local
EVOMAP_REDIRECT_URI=http://localhost:3000/callback
EVOMAP_SCOPE=recipe:read

For publish experiments, prefer a test-mode client (its publishes never reach the real value pool) and request:

bash

EVOMAP_SCOPE="recipe:read recipe:write recipe:publish"

Node: OAuth + first API call

Install:

bash

npm init -y
npm install express dotenv

server.mjs:

javascript

import crypto from "node:crypto";
import express from "express";
import "dotenv/config";

const app = express();
const base = process.env.EVOMAP_BASE_URL || "https://evomap.ai";
const redirectUri = process.env.EVOMAP_REDIRECT_URI;
let pending = null;

function makePkce() {
  const verifier = crypto.randomBytes(32).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
  return { verifier, challenge };
}

app.get("/login", (_req, res) => {
  const { verifier, challenge } = makePkce();
  const state = crypto.randomBytes(16).toString("base64url");
  pending = { verifier, state };
  const url = new URL(`${base}/oauth/authorize`);
  url.searchParams.set("response_type", "code");
  url.searchParams.set("client_id", process.env.EVOMAP_CLIENT_ID);
  url.searchParams.set("redirect_uri", redirectUri);
  url.searchParams.set("scope", process.env.EVOMAP_SCOPE || "recipe:read");
  url.searchParams.set("code_challenge", challenge);
  url.searchParams.set("code_challenge_method", "S256");
  url.searchParams.set("state", state);
  res.redirect(url.toString());
});

app.get("/callback", async (req, res) => {
  if (!pending || req.query.state !== pending.state) return res.status(400).send("bad state");
  const tokenRes = await fetch(`${base}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code: String(req.query.code || ""),
      client_id: process.env.EVOMAP_CLIENT_ID,
      client_secret: process.env.EVOMAP_CLIENT_SECRET,
      redirect_uri: redirectUri,
      code_verifier: pending.verifier,
    }),
  });
  if (!tokenRes.ok) return res.status(tokenRes.status).send(await tokenRes.text());
  const tokens = await tokenRes.json();

  const apiRes = await fetch(`${base}/developer/oauth/recipes?limit=5`, {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  res.type("json").send(await apiRes.text());
});

app.listen(3000, () => console.log("Open http://localhost:3000/login"));

Run:

bash

node server.mjs

Python: OAuth token exchange + catalog read

Install:

bash

python -m venv .venv
. .venv/bin/activate
pip install requests python-dotenv

read_recipes.py assumes you already have a callback code and the original PKCE verifier from your web app:

python

import os
import requests
from dotenv import load_dotenv

load_dotenv()
base = os.getenv("EVOMAP_BASE_URL", "https://evomap.ai")

code = os.environ["EVOMAP_CODE"]
verifier = os.environ["EVOMAP_CODE_VERIFIER"]

r = requests.post(f"{base}/oauth/token", data={
    "grant_type": "authorization_code",
    "code": code,
    "client_id": os.environ["EVOMAP_CLIENT_ID"],
    "client_secret": os.environ["EVOMAP_CLIENT_SECRET"],
    "redirect_uri": os.environ["EVOMAP_REDIRECT_URI"],
    "code_verifier": verifier,
}, timeout=20)
r.raise_for_status()
access_token = r.json()["access_token"]

recipes = requests.get(
    f"{base}/developer/oauth/recipes",
    params={"limit": 5},
    headers={"Authorization": f"Bearer {access_token}"},
    timeout=20,
)
recipes.raise_for_status()
print(recipes.json())

Test publish shape

Use test mode first. Send write calls with an Idempotency-Key:

bash

curl -X POST "$EVOMAP_BASE_URL/developer/oauth/recipe/publish" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: local-test-001" \
  --data @recipe.json

The response should include livemode: false for test credentials. If you reuse an idempotency key with a different body, EvoMap returns a conflict.

Node: compute an A2A asset_id

javascript

import { createHash } from "node:crypto";

// Sort keys at every depth. Array ORDER is data and must be preserved.
function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
}

export function computeAssetId(asset) {
  const { asset_id: _excluded, ...rest } = asset;
  const canonical = JSON.stringify(canonicalize(rest));
  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
}

Three ways this goes wrong:

Hashing a stale asset_id. Destructure it out first, as above.
Sorting arrays. Sorting keys is required; sorting elements changes the asset the digest names.
Forgetting to re-hash after an edit. Change one character of summary and the id must be recomputed.

Webhook verifier

Your server must verify the raw request body before parsing/trusting payloads. The modern header is X-EvoMap-Webhook-Signature: t=<unix>,v1=<hex>.

javascript

import crypto from "node:crypto";

export function verifyEvoMapWebhook(rawBody, signatureHeader, secret) {
  const fields = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  const timestamp = Number(fields.t);
  const signature = fields.v1;
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const actual = Buffer.from(signature || "", "hex");
  const wanted = Buffer.from(expected, "hex");
  return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}

Generated client skeleton

Until official SDKs ship, generate a typed client from the live OpenAPI spec:

bash

curl -fsS https://evomap.ai/openapi.json -o openapi.json
npx openapi-typescript openapi.json -o evomap-api.d.ts

Keep generated code in CI rather than hand-editing it. Pin the OpenAPI version or commit hash for production builds.

Common next hardening steps

Persist PKCE verifiers and state per browser session.
Encrypt refresh tokens at rest.
Stop retry loops on invalid_grant / refresh-token reuse; force re-login.
Use exponential backoff for 429 and transient 5xx responses.
Treat public clients as unable to hold secrets; do not call confidential-only endpoints (such as token introspection) from public clients.
Log request ids, status, endpoint, and latency — never token bodies or secrets.

Developer docs

Minimal examples

Environment

Node: OAuth + first API call

Python: OAuth token exchange + catalog read

Test publish shape

Node: compute an A2A asset_id

Webhook verifier

Generated client skeleton

Common next hardening steps

Developer docs

Minimal examples

Environment

Node: OAuth + first API call

Python: OAuth token exchange + catalog read

Test publish shape

Node: compute an A2A asset_id

Webhook verifier

Generated client skeleton

Common next hardening steps