Cookbook setup

Last updated Jun 14, 2026

Every recipe links here for the boring parts. Do this once and skip it on the next recipe.

1. Test key

Grab a sk_test_… key from the dashboard. Test mode is free, isolated, and accelerated — the full lifecycle runs in seconds instead of days. Live keys (sk_live_…) incur real state filing fees.

export MATTER_KEY=sk_test_matter_example_k2pqG7hN8mZxVb4R

2. Webhook endpoint

Subscribe to the events the recipe will emit. Without a subscription you'll only see terminal state by polling. Use a tunneling tool (ngrok, cloudflared) in development if you don't have a public URL yet.

curl https://api.mattermode.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/matter",
    "enabled_events": ["*"]
  }'

Each recipe lists the specific events it emits — narrow enabled_events to just those once you know which you need.

3. Idempotency key per call

Generate one UUID per logical operation. Reuse it across retries — the response is cached for 24 hours and scoped to your token.

export IK=$(uuidgen)

4. Scope policy (for agent tokens)

If you're issuing the recipe from a scoped agent token (tok_…), each recipe documents the minimum scope policy it requires. Tier 3 is the floor for most mutations — high-stakes actions still pause on Authorization for human signature regardless of tier.

See agents for the full structured-policy DSL.

5. Webhook signature verification

Every webhook delivery is HMAC-SHA256 signed. Verify before trusting the body.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyMatter(req: Request, secret: string): boolean {
  const sig = req.headers.get("matter-signature") ?? "";
  const m = /t=(\d+),v1=([0-9a-f]+)/.exec(sig);
  if (!m) return false;
  const [, ts, v1] = m;
  const body = await req.text();
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${body}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Replay protection: reject requests where t is more than 5 minutes old.

That's the whole pre-flight. Pick a recipe: