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
/api/v1/sessionsLegt eine Test-Session an und liefert den Link für die Testperson./api/v1/sessionsListet die letzten 100 Sessions deiner Organisation (optional ?status=completed)./api/v1/sessions/:idStatus, Ergebnis und signiertes Token einer Session./.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" | standard | Schnell: 8–12 Aufgaben. Standard: 16–28, stoppt bei ausreichender Messgenauigkeit. |
| domains | string[] | alle | matrix, series, verbal, spatial |
| reference | string | — | Deine ID für die Person (max. 200 Zeichen). Landet im Token und Webhook. |
| redirect_url | URL | — | Nach dem Test wird dorthin weitergeleitet, mit ?session_id=… |
| webhook_url | URL | — | Erhält bei Abschluss einen POST mit dem Token. |
| expires_in | Sekunden | 604800 | Wie 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)