API-Referenz — Übersicht

Alles, was Sie brauchen, um von Null zu Ihrem ersten humanToken zu gelangen.

Markdown

Human Token verfügt über drei Endpunkte. Diese Seite zeigt, wie sie zusammenwirken, damit Sie sofort mit der Integration beginnen können.

Basis-URL

Umgebung	Basis-URL
Produktion	https://humantoken.unico.app

Alle Anfragen erfordern den Header x-unico-accesskey. Unter Authentifizierung erfahren Sie, wie Sie Ihren Schlüssel generieren.

---

Schnellstart-Ablauf

---

Schritt 1 — Authentifizierung

Generieren Sie Ihren x-unico-accesskey im Human Dashboard oder über die Authentication API. Jede nachfolgende Anfrage verwendet diesen Schlüssel.

x-unico-accesskey: uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2

---

Schritt 2 — Prozess erstellen

Rufen Sie Create Process auf, um die Verifizierung zu starten. Wählen Sie eines von zwei Modellen:

Modell	Flows	Funktionsweise
API Only	api+humantoken, api+liveness+humantoken, api+liveness+humantoken+revalidation	Ihr Backend sendet das Selfie als imageBase64. Der humanToken wird in derselben Antwort zurückgegeben.
Human Token Journey	humantoken, humantoken+revalidation	Der Benutzer schließt die Aufnahme auf der Unico-Plattform ab. Sie erhalten ein token und einen link, um die Journey zu präsentieren, und rufen das Ergebnis dann mit Get Process ab.

API Only Beispiel:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "api+humantoken",
    "imageBase64": "<base64-encoded-selfie>",
    "companyBranchId": "<your-branch-id>"
  }'

Human Token Journey Beispiel:

curl -X POST https://humantoken.unico.app/client/v1/process \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flow": "humantoken",
    "callbackUri": "https://yourapp.com/callback",
    "companyBranchId": "<your-branch-id>"
  }'

Siehe Create Process für alle Flows, Parameter und Antwortdetails.

---

Schritt 3 — Die Journey dem Benutzer präsentieren (nur Journey-Flows)

Für die Flows humantoken und humantoken+revalidation enthält die Antwort von Create Process:

• token — initialisiert das Web SDK oder die native Integration
• link — URL, zu der der Benutzer weitergeleitet wird

Wählen Sie die Integration, die zu Ihrer Plattform passt:

Plattform	Ansatz
Web — SDK	Journey inline einbetten mit idpay-b2b-sdk → Web Integration
Web — Redirect	Benutzer zu link weiterleiten → Web Integration
Android	Custom Tabs → Android
iOS	ASWebAuthenticationSession → iOS
Ionic	Capacitor plugin → Ionic
React Native	Native module → React Native
Flutter	Platform Channels → Flutter

Wenn die Journey endet, kehrt der Benutzer zu Ihrer callbackUri zurück. Fahren Sie mit Schritt 4 fort.

API Only Flows

Überspringen Sie diesen Schritt — das Ergebnis befindet sich bereits in der Antwort von Create Process.

---

Schritt 4 — Ergebnis abrufen (nur Journey-Flows)

Rufen Sie Get Process mit der Prozess-id auf, um das Ergebnis abzurufen:

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

Die Antwort enthält data.humanToken.value (Standard-Flows) oder data.humanTokenMatch (Revalidierungs-Flows). Siehe Get Process für das vollständige Antwortschema und die Statuswerte.

---

Schritt 5 — humanToken verwenden

Der humanToken ist ein stabiler, opaker Bezeichner (bis zu 100 Zeichen). Dieselbe Person wird immer zum selben Wert aufgelöst.

const { humanToken } = process.data;

if (!humanToken?.value) {
  // Inconclusive — retry or reject per your business rules
  return;
}

const existing = await db.persons.findByHumanToken(humanToken.value);

if (existing) {
  // Same person seen before — returning user or duplicate
} else {
  // First time — create a new record
  await db.persons.create({ humanToken: humanToken.value });
}

Warnung

Überprüfen Sie immer, dass data.humanToken.value nicht leer ist, bevor Sie ihn speichern oder abgleichen.

---

Schritt 6 — Selfie abrufen (optional)

Rufen Sie Get Selfie auf, um das aufgenommene Bild herunterzuladen. Das Selfie ist 24 Stunden nach Abschluss des Prozesses verfügbar — danach wird es dauerhaft gelöscht.

curl https://humantoken.unico.app/client/v1/process/$PROCESS_ID/selfie \
  -H "x-unico-accesskey: $UNICO_ACCESS_KEY"

Siehe Get Selfie für Antwortdetails und Fehlercodes.

---

Endpunkte auf einen Blick

Methode	Endpunkt	Beschreibung
POST	/client/v1/process	Create Process — Verifizierung starten
GET	/client/v1/process/{processId}	Get Process — Ergebnis abrufen
GET	/client/v1/process/{processId}/selfie	Get Selfie — Selfie herunterladen (24 Std.)

Nächste Schritte

• Create Process — vollständige Parameterreferenz für alle fünf Flows
• Authentication — Zugriffsschlüssel generieren und verwalten
• Build With LLM — Fügen Sie einen Prompt in Ihren KI-Assistenten ein, um die vollständige Integration zu generieren