Maxiaa Partner API

Wwft-proof identiteitsverificatie, zonder gedoe. Sluit je software aan met een API-sleutel: start een verificatie, volg de status, en ontvang een ondertekende webhook zodra het verdict klaar is.

Base-URL

https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1

Quickstart — je eerste verificatie in 5 minuten

1. Log in op de console en maak een sandbox-sleutel (mxa_test_…).
2. Start een verificatie, rond 'm af in sandbox, lees het verdict:

# 1. Start een verificatie (sandbox)
curl -X POST https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1/verifications \
  -H "Authorization: Bearer mxa_test_je_sleutel" \
  -H "Content-Type: application/json" \
  -d '{ "method": "document_liveness", "reference": "klant-8821",
        "sandbox": { "scenario": "approved", "auto_complete": false } }'

# 2. Rond de sandbox-verificatie af (simuleert de verify-link met een specimen)
curl -X POST https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1/verifications/{id}/complete \
  -H "Authorization: Bearer mxa_test_je_sleutel"

# 3. Vraag status + verdict op
curl https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1/verifications/{id} \
  -H "Authorization: Bearer mxa_test_je_sleutel"

Zelfde flow in Node:

import fetch from "node-fetch"; // of native fetch in Node 18+
const KEY = process.env.MAXIAA_KEY;         // mxa_test_…
const BASE = "https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1";
const h = { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" };

const created = await (await fetch(`${BASE}/verifications`, {
  method: "POST", headers: h,
  body: JSON.stringify({ method: "document_liveness", reference: "klant-8821",
    sandbox: { scenario: "approved", auto_complete: false } }),
})).json();

await fetch(`${BASE}/verifications/${created.id}/complete`, { method: "POST", headers: h });

const result = await (await fetch(`${BASE}/verifications/${created.id}`, { headers: h })).json();
console.log(result.verdict.outcome); // "approved"

In sandbox zonder auto_complete:false is de verificatie meteen klaar (voorspelbaar verdict). Zet auto_complete:false om de asynchrone levenscyclus (pending → webhook → completed) na te bootsen.

Authenticatie

Elke aanroep gebruikt een API-sleutel in de Authorization-header:

Authorization: Bearer mxa_live_…   (productie)
Authorization: Bearer mxa_test_…   (sandbox)

De sleutel bepaalt de omgeving (sandbox/live) én de org. Sleutels worden alleen als SHA-256-hash bewaard — je ziet de volledige sleutel maar één keer. Scopes: verify:create, verify:read, webhooks:manage. Een sleutel zonder de juiste scope krijgt 403 insufficient_scope.

Sandbox-modus

Met een mxa_test_-sleutel draai je de volledige integratie zonder productiedata en zonder kosten. Sandbox-verificaties geven een voorspelbaar verdict op basis van het scenario:

Sandbox-verbruik verschijnt nooit op een factuur. Live-verificaties (mxa_live_) worden door de eindgebruiker via de verify_url doorlopen; afronden-via-API bestaat alleen in sandbox.

Rate limits

Per sleutel geldt een limiet per minuut (standaard 120). Elk antwoord bevat X-RateLimit-Limit en X-RateLimit-Remaining. Over de limiet → 429 rate_limit_exceeded met een Retry-After-header.

Idempotency

Stuur een Idempotency-Key-header op POST /verifications om veilig te herhalen bij netwerkfouten. Dezelfde sleutel + dezelfde body geeft exact hetzelfde antwoord (er ontstaat geen tweede verificatie). Dezelfde sleutel met een andere body → 422 idempotency_key_reused.

curl -X POST https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1/verifications \
  -H "Authorization: Bearer mxa_test_…" \
  -H "Idempotency-Key: 6f1c-…-a2" \
  -H "Content-Type: application/json" -d '{"reference":"klant-8821"}'

Foutmodel

Fouten zijn altijd JSON met een vast formaat + een request_id (ook als header X-Request-Id):

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Onbekende of ingetrokken API-sleutel.",
    "request_id": "req_…"
  }
}

Webhooks & signing

Registreer een endpoint (het secret wordt éénmalig getoond):

curl -X POST https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/v1/webhooks \
  -H "Authorization: Bearer mxa_test_…" -H "Content-Type: application/json" \
  -d '{"url":"https://jouw-app.nl/webhooks/maxiaa","environment":"all"}'

Zodra een verdict klaar is, sturen wij een POST naar je URL met dit event:

{
  "id": "evt_2b1c…",
  "type": "verification.completed",
  "created": 1783900000,
  "environment": "sandbox",
  "data": {
    "verification_id": "b3f1…",
    "reference": "klant-8821",
    "status": "completed",
    "outcome": "approved",
    "assurance_level": "substantial",
    "reasons": []
  }
}

Headers: X-Maxiaa-Signature: t=<unix>,v1=<hex>, X-Maxiaa-Event, X-Maxiaa-Delivery (uniek event-id, gebruik het voor idempotentie aan jouw kant).

Signature verifiëren

Bereken HMAC-SHA256(secret, "<timestamp>.<ruwe body>") en vergelijk constant-time met v1. Verwerp events ouder dan 5 minuten (replay-bescherming).

import crypto from "node:crypto";

// Express-voorbeeld — verifieer de X-Maxiaa-Signature op je webhook-endpoint.
export function verifyMaxiaaSignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay-bescherming
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ""));
}

app.post("/webhooks/maxiaa", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verifyMaxiaaSignature(req.body.toString(), req.get("X-Maxiaa-Signature"), process.env.WHSEC);
  if (!ok) return res.status(400).send("bad signature");
  const event = JSON.parse(req.body.toString());
  if (event.type === "verification.completed") { /* verwerk event.data.outcome */ }
  res.sendStatus(200);
});

import hmac, hashlib, time

def verify_maxiaa_signature(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts["t"])
    if abs(time.time() - t) > tolerance:      # replay-bescherming
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# Flask
@app.post("/webhooks/maxiaa")
def hook():
    if not verify_maxiaa_signature(request.get_data(), request.headers["X-Maxiaa-Signature"], WHSEC):
        return "bad signature", 400
    event = request.get_json()
    # event["type"] == "verification.completed" -> event["data"]["outcome"]
    return "", 200

Bij een non-2xx antwoord retryen we met exponentiële backoff (tot 6 pogingen, ~8 uur). Antwoord 2xx zodra je het event veilig hebt vastgelegd.

MCP-server — voor AI-agents en assistenten

Naast de REST-API draaien wij een MCP-server (Model Context Protocol). Daarmee kan een AI-assistent — Claude Code, Claude Desktop, of je eigen agent — zelf een verificatie starten en de status opvolgen, zonder dat jij daar integratiecode voor schrijft.

Installeren

Eén regel. Gebruik je sandbox-sleutel om te oefenen:

claude mcp add maxiaa --scope user --transport http \
  https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp \
  --header "Authorization: Bearer mxa_test_je_sleutel"

Andere clients: endpoint https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp, transport streamable HTTP, en de sleutel als Authorization: Bearer-header. Er is geen aparte MCP-sleutel — het is dezelfde partner-API-sleutel, met dezelfde scopes, dezelfde rate limit en hetzelfde request-logboek.

De grens — lees dit vóór je hem aanzet

Endpoints die bewust géén tool zijn

Velden die nooit worden teruggegeven

Beschikbare tools

Zonder geldige sleutel krijgt een agent géén toollijst. complete_verification bestaat alleen met een sandbox-sleutel; met een live-sleutel staat hij niet eens in de lijst. Lijsten zijn gepagineerd met een harde bovengrens van 25 per aanroep.

Over de gezichtsvergelijking zijn de toolbeschrijvingen expliciet: het is een indicatieve AI-controle met een menselijke eindbeoordeling, geen zelfstandig biometrisch bewijs. Een agent die dat leest, presenteert approved hopelijk ook zo.

Sandbox-voorbeeld

Wil je het protocol handmatig zien, dan is dit de volledige rondrit met curl:

KEY=mxa_test_je_sleutel

# 1. handshake
curl -s https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"mijn-agent","version":"1.0"}}}'

# 2. welke tools heb ik?
curl -s https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. een verificatie starten (sandbox: meteen een voorspelbaar oordeel)
curl -s https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"start_verification",
                 "arguments":{"method":"document_liveness","reference":"klant-8821",
                              "sandbox_scenario":"approved"}}}'

Het antwoord op stap 3 — let op wat er niet in staat:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ … }"
      }
    ],
    "structuredContent": {
      "id": "b3f1c8a2-…",
      "object": "verification",
      "status": "completed",
      "environment": "sandbox",
      "method": "document_liveness",
      "created_at": "2026-08-06T10:00:00.000Z",
      "verdict": {
        "outcome": "approved",
        "assurance_level": "substantial",
        "reviewed": false,
        "checks": [
          {
            "kind": "document_authenticity",
            "result": "pass",
            "confidence": 0.97
          },
          {
            "kind": "face_match",
            "result": "pass",
            "confidence": 0.93
          }
        ]
      },
      "verify_url": "https://…/?t=vr_…",
      "next_step": "Stuur verify_url naar de eindgebruiker. Volg daarna get_verification tot status 'completed'."
    },
    "isError": false
  }
}

Geen reference, geen dossier_ref, geen vrije tekst. De verify_url is de enige plek waar een token naar buiten komt — die moet jij naar je eindgebruiker sturen, en hij verschijnt nooit bij opvragen of in een lijst.

Fouten

Protocolfouten zijn JSON-RPC-fouten; een tool die zijn werk niet kan doen (verificatie niet gevonden, verkeerde omgeving) geeft een normaal resultaat met isError: true, zodat de agent zichzelf kan corrigeren.

GET https://wkrhvuxmsbvzqluwigst.supabase.co/functions/v1/mcp geeft bewust 405: deze server biedt geen server-naar-client-stroom aan en is stateless — er is dus ook geen sessie-id.

Endpoint-referentie

Gegenereerd uit de OpenAPI-spec (openapi.yaml · openapi.json).

Changelog

• v1.1.0 — MCP-server voor AI-agents (streamable HTTP, JSON-RPC 2.0) op dezelfde API-sleutel. Bewust smaller dan de REST-API: geen inkomensmodule, geen dossierverwijzing, geen persoonsgegevens. De REST-API is ongewijzigd.
• v1.0.0 — Eerste publieke release: /v1/verifications, /v1/webhooks, API-key-auth, sandbox, HMAC-signed webhooks, rate-limiting, idempotency, OpenAPI 3.0-spec.

© 2026 Maxiaa · OpenAPI