Referenz

API-Doku

Der Ablauf ist derselbe wie bei Identitätsprüfungen: Du legst eine Session an, schickst den Link, die Person macht den Test und du bekommst ein signiertes Ergebnis zurück. API-Keys erstellst du im Dashboard.

Endpunkte

POST/api/v1/sessionsLegt eine Test-Session an und liefert den Link für die Testperson.
GET/api/v1/sessionsListet die letzten 100 Sessions deiner Organisation (optional ?status=completed).
GET/api/v1/sessions/:idStatus, Ergebnis und signiertes Token einer Session.
GET/.well-known/jwks.jsonÖffentliche Schlüssel zum Prüfen der Tokens.

1. Session anlegen

curl -X POST https://<host>/api/v1/sessions \
  -H "Authorization: Bearer iqk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "standard",
    "domains": ["matrix", "series", "verbal", "spatial"],
    "reference": "discord:123456789",
    "redirect_url": "https://example.com/done",
    "webhook_url": "https://example.com/hooks/iq",
    "expires_in": 604800
  }'
Feld Typ Default Beschreibung
mode"quick" | "standard"standardSchnell: 8–12 Aufgaben. Standard: 16–28, stoppt bei ausreichender Messgenauigkeit.
domainsstring[]allematrix, series, verbal, spatial
referencestring—Deine ID für die Person (max. 200 Zeichen). Landet im Token und Webhook.
redirect_urlURL—Nach dem Test wird dorthin weitergeleitet, mit ?session_id=…
webhook_urlURL—Erhält bei Abschluss einen POST mit dem Token.
expires_inSekunden604800Wie lange der Link gestartet werden kann (300 s – 30 Tage).

Antwort (201):

{
  "id": "Xq3...",
  "url": "https://<host>/t/Xq3...",
  "status": "pending",
  "mode": "standard",
  "reference": "discord:123456789",
  "expires_at": "2026-11-24T10:00:00.000Z",
  "result": null,
  "token": null,
  ...
}

2. Link an die Person schicken

url öffnet den Test. Der Link ist das Zugangsrecht, also behandle ihn wie ein Einmal-Passwort. Gestartete Tests müssen innerhalb von 2 Stunden beendet werden.

3. Ergebnis empfangen

Per Webhook (bis zu 3 Versuche, 5 s Timeout) oder per Polling auf GET /api/v1/sessions/:id.

POST <webhook_url>
{
  "event": "session.completed",
  "session_id": "Xq3...",
  "reference": "discord:123456789",
  "token": "eyJhbGciOiJFUzI1NiIs..."
}

4. Token prüfen

Das Token ist ein ES256-JWT. Webhooks selbst sind nicht signiert, deshalb solltest du immer das Token prüfen. Dafür reicht der öffentliche Schlüssel; einem Webhook-Aufruf musst du nicht vertrauen. aud ist die ID deiner Organisation (siehe Einstellungen im Dashboard).

import { createRemoteJWKSet, jwtVerify } from 'jose'

const JWKS = createRemoteJWKSet(new URL('https://<host>/.well-known/jwks.json'))

const { payload } = await jwtVerify(token, JWKS, {
  issuer: 'https://<host>',
  audience: '<deine Organisations-ID>'
})
// payload.iq, payload.ci95, payload.percentile, payload.domains,
// payload.integrity, payload.reference, payload.sub (= session id)
Grenzen
Ergebnisse sind unbeaufsichtigt (assurance: unproctored) und vorläufig normiert (norm: provisional). integrity.level meldet Tab-Wechsel, Vollbild-Abbrüche und verdächtig schnelle Antworten. Nutze die Ergebnisse nicht für Personalentscheidungen.