Entwickler · Schnellstart

In 10 Minuten zum ersten allow

Ihr Agent fragt Mandact vor jeder Handlung und handelt nur bei «allow». Für einen Test braucht es weder Zahlungsmittel noch Händler: Erfinden Sie eine Handlung, etwa «Hardware bis CHF 500 bei ACME AG», und schicken Sie verschiedene Beträge und Gegenparteien. Sie sehen allow, deny mit Grund, Eskalation und den Beleg.

1. 1 · Konto anlegen

   Registrieren und den zweiten Faktor einrichten. Ohne ihn lassen sich keine API-Schlüssel erzeugen.

2. 2 · Agent und Mandat anlegen

   Neues Mandat im Assistenten. Im Schritt «Agent» die Kennung leer lassen (Weg 1) oder die did:key Ihres Agenten eintragen (Weg 2). Grenzen setzen: Handlungstyp, Betrag pro Handlung und Monat, Gegenpartei, Eskalationsschwelle. Den gebundenen Wortlaut prüfen und das Mandat aktivieren.

3. 3 · API-Schlüssel erzeugen

   Einstellungen → API-Schlüssel → Umgebung «Produktion». Rechte: Für eigene Agenten handeln (agents:present), Beleg prüfen (verify), Reservierungen einlösen (consumptions:write), Ausführungen melden (executions:write), Mandate lesen (mandates:read), Beweiskette lesen (evidence:read). Der Schlüssel wird genau einmal angezeigt.

4. 4 · Die drei Aufrufe einbauen

   Vor der Handlung signieren lassen und prüfen, danach verbuchen und melden. Die Mandats-ID steht auf der Detailseite des Mandats.

Die Aufrufe

Umgebung: MANDACT_API_KEY und MANDATE_ID. Die Handlung muss bei present und verify identisch sein — beide Seiten binden denselben Kontext-Digest.

curl -s -X POST https://mandact.com/api/v1/agents/present \
  -H "authorization: Bearer $MANDACT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"mandate_id":"'$MANDATE_ID'",
       "action":{"type":"purchase.goods",
                 "amount":{"value":120,"currency":"CHF"},
                 "counterparty":"ACME AG"}}' > pres.json
# → { presentation, custody: "custodial", note }

curl -s -X POST https://mandact.com/api/v1/verify \
  -H "authorization: Bearer $MANDACT_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"presentation":'"$(jq .presentation pres.json)"',
       "action":{"type":"purchase.goods",
                 "amount":{"value":120,"currency":"CHF"},
                 "counterparty":"ACME AG"}}'
# → allow:    { decision, consumption_token, receipt, mat_compact }
# → deny:     { decision, reasons: ["MD-302"], reason_text, receipt }
# → escalate: { decision, escalation: { id, expires_at } }

curl -s -X POST https://mandact.com/api/v1/consumptions \
  -H "authorization: Bearer $MANDACT_API_KEY" -H "content-type: application/json" \
  -d '{"consumption_token":"<token>","final_amount":120,"currency":"CHF",
       "action_type":"purchase.goods","counterparty":"ACME AG",
       "context_digest":"'"$(jq -r .presentation.ctx pres.json)"'"}'
curl -s -X POST https://mandact.com/api/v1/executions \
  -H "authorization: Bearer $MANDACT_API_KEY" -H "content-type: application/json" \
  -d '{"reservation_token":"<token>","outcome":"erfolgreich",
       "executed_amount":120,"executed_currency":"CHF","external_ref":"PO-4711"}'

curl -s "https://mandact.com/api/v1/verifications/<rcp_…>/dossier?mat=<mat_compact>" \
  -H "authorization: Bearer $MANDACT_API_KEY" > dossier.json
node verify-dossier.mjs dossier.json --mat <mat_compact>
# → VALID … MAT: gueltig (ES256, kid …)

Weg 2: Der Agent signiert selbst

Der Beispiel-Agent erzeugt einen Ed25519-Schlüssel und zeigt dessen did:key. Diese tragen Sie im Assistenten bei «Kennung» ein; Mandact speichert nur den öffentlichen Schlüssel und signiert für diesen Agenten nie. Die Presentation muss die Organisation mitsignieren, bei der sie geprüft wird — den Wert liefert der Status-Endpunkt als presentation_verifier.

node beispiel-agent.mjs schluessel
# → agent-key.pem + did:key:z6Mk…
curl -s https://mandact.com/api/v1/mandates/$MANDATE_ID/status -H "authorization: Bearer $MANDACT_API_KEY"
# → { limits, agent_did, presentation_verifier }
AGENT_KEY_FILE=agent-key.pem node beispiel-agent.mjs allow

Weg 3: Durch das Gateway

Zum Ausprobieren ohne eigenes Zielsystem gibt es ein neutrales Echo-Ziel, das nur zurücksagt, was ankam — ohne Nebeneffekte.

1. Connectoren → «Eigenes Tool anbinden» → Instanz anlegen. Unter «Gateway einrichten»: Upstream-URL https://mandact.com/api/sandbox/echo, ein Upstream-Secret mit mindestens 16 Zeichen, Mandat wählen → «Gateway-Token erzeugen». Das Token gwt_… wird einmal angezeigt.
2. Einen ersten POST an https://mandact.com/api/gateway/http/bestellung senden. Mandact legt das Werkzeug «http.post:/bestellung» an und lehnt mit MD-301 ab, solange es keiner Handlung Ihres Mandats zugeordnet ist.
3. In der Instanz «Tools neu laden», dem Werkzeug unter «Von Ihren aktiven Mandaten gedeckt» die Handlung zuordnen (etwa purchase.goods) und speichern. Danach entscheidet das Mandat — auch über das Monatsbudget.

curl -s -X POST https://mandact.com/api/gateway/http/bestellung \
  -H "authorization: Bearer $GATEWAY_TOKEN" -H "content-type: application/json" \
  -d '{"amount":120,"currency":"CHF","counterparty":"ACME AG"}' -i
# allow → X-Mandact-Decision: allow, X-Mandact-Receipt: rcp_…
# deny  → HTTP 403 { error: "mandact_deny", reasons, receipt_id }

Der Beispiel-Agent

Eine Datei, nur Node ≥ 20, keine Abhängigkeiten. Er liest die Grenzen Ihres Mandats und spielt alle drei Wege durch: pruefen, schluessel, allow, ablehnungen, gateway. Konfiguration über MANDACT_API_KEY, MANDATE_ID und optional AGENT_KEY_FILE bzw. GATEWAY_TOKEN. Den Dossier-Prüfer neben den Agenten legen, dann prüft er jedes Dossier offline.