Authentifizierung

Markdown

Diese Anleitung führt Sie durch die Authentifizierung beim Human Dashboard und die Generierung des x-unico-accesskey, den Sie in allen Human Token API-Anfragen verwenden.

Der Ablauf hat zwei Phasen:

Authentifizieren — schließen Sie eine Anmeldung ab und erhalten Sie ein Zugriffstoken. Zwei Authentifizierungsmethoden stehen zur Verfügung:
- Biometrische Anmeldung — Gesichtserfassung über das Unico SDK (verfügbar für Registrierung und Anmeldung)
- Anmeldung per E-Mail-OTP — einmaliger Code, der an die registrierte E-Mail-Adresse gesendet wird (nur Anmeldung)
Organisation einrichten — erstellen Sie Ihr Unternehmensprofil und generieren Sie einen Zugriffsschlüssel (nur bei der ersten Registrierung)

Zwei Wege, Ihre Zugangsdaten einzurichten

Alles in dieser Anleitung kann auch über das Human Dashboard unter dashboard.unico.app erledigt werden — ganz ohne API-Aufrufe.

Option	Wann verwenden
Dashboard	Ersteinrichtung, manuelle Schlüsselrotation, gelegentliche Verwaltung
API	Automatisierte Bereitstellung, CI/CD-Pipelines, programmatische Schlüsselverwaltung

Über das Dashboard

Rufen Sie dashboard.unico.app auf
Registrieren oder anmelden — verwenden Sie die biometrische Anmeldung (Gesichtserfassung) oder E-Mail-OTP
Organisation erstellen — geben Sie Ihren Unternehmensnamen, das Land und die erlaubten Domains ein
Zugriffsschlüssel generieren — gehen Sie zu Access Keys und klicken Sie auf Create key; kopieren Sie ihn sofort, er wird nur einmal angezeigt
Branches verwalten — erstellen und konfigurieren Sie Branches unter Branches; jeder Branch generiert seinen eigenen Zugriffsschlüssel

Der Zugriffsschlüssel, den Sie über das Dashboard erhalten, ist derselbe x-unico-accesskey, der in allen API-Anfragen verwendet wird — beide Wege sind vollständig austauschbar.

Basis-URLs

Jeder Endpunkt auf dieser Seite wird von der Human Dashboard API bereitgestellt. Die Anfragen an die Human Token API, wie Create Process und Get Process, gehen an den API-Host, der unter Umgebungen aufgeführt ist.

Umgebung	API	Basis-URL
Produktion	Human Dashboard API (Anmeldung, Organisation, Zugriffsschlüssel und Branches)	`https://api.humantoken.unico.app`

Authentifizierungsmethoden

Zwei Methoden stehen zur Verfügung, um sich zu authentifizieren und ein authToken zu erhalten:

Methode	Endpunkt	Wann verwenden
Biometrisch	`POST /api/console/v1/auth/biometric/sessions`	Registrierung (neues Konto) oder Anmeldung (wiederkehrender Nutzer)
E-Mail-OTP	`POST /api/console/v1/auth/email/sessions`	Nur Anmeldung — das Konto muss bereits existieren

Intent der biometrischen Anmeldung

Jeder Aufruf von POST /api/console/v1/auth/biometric/sessions muss einen intent angeben:

`intent`	Wann verwenden	Feld `email`	Feld `name`
`LOGIN_INTENT_SIGNUP`	Erstregistrierung — Erstellen eines neuen Kontos	Erforderlich	Erforderlich
`LOGIN_INTENT_SIGNIN`	Wiederkehrender Nutzer — das Konto existiert bereits	Nicht verwendet	Nicht verwendet
(weggelassen)	Wird als `LOGIN_INTENT_SIGNIN` behandelt	Nicht verwendet	Nicht verwendet

Der Intent steuert die Validierung, die beim Abfragen der Sitzung (Schritt 2) erfolgt:

SIGNUP — lehnt die Anmeldung ab, wenn diese biometrische Identität bereits registriert ist (verhindert doppelte Konten).
SIGNIN — lehnt die Anmeldung ab, wenn diese biometrische Identität nicht registriert ist (das Konto muss für die Anmeldung existieren).

Phase 1 — Authentifizieren

Schritt 1: Eine biometrische Anmeldesitzung starten

SIGNUP (Erstregistrierung)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

Eindeutigkeit der E-Mail

Wenn mit dieser E-Mail bereits ein Konto registriert ist, gibt die Anfrage 400 Bad Request zurück.

Antwort:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

Bei SIGNUP sind die Felder link und token in der Antwort leer — der Link für die biometrische Erfassung wird an die angegebene E-Mail-Adresse gesendet.

SIGNIN (wiederkehrender Nutzer)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

Antwort:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Speichern Sie die sessionId.

SIGNUP: Der Link für die biometrische Erfassung wird an die in Schritt 1 angegebene E-Mail gesendet. Bitten Sie den Nutzer, seinen Posteingang zu prüfen und die Erfassung abzuschließen.
SIGNIN: Öffnen Sie link in Ihrem Browser und schließen Sie die biometrische Erfassung ab.

Schritt 2: Abfragen, bis die Sitzung aufgelöst ist

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

Fragen Sie alle 2–3 Sekunden ab, bis status einen Endzustand erreicht.

`status`	`outcome`	Bedeutung
`pending`	`pending`	Der Nutzer hat die Erfassung noch nicht abgeschlossen — weiter abfragen
`processing`	`pending`	Erfassung abgeschlossen, Ergebnisse werden berechnet — weiter abfragen
`completed`	`matched`	Anmeldung erfolgreich — `authToken` ist vorhanden
`completed`	`no_match`	Die Biometrie stimmte mit keinem Datensatz überein
`completed`	`inconclusive`	Erfassung erfolgreich, konnte aber nicht aufgelöst werden
`expired`	—	Link abgelaufen — ab Schritt 1 neu beginnen
`canceled`	—	Sitzung wurde abgebrochen — ab Schritt 1 neu beginnen

Zusätzliche Intent-spezifische Fehler beim Abfragen der Sitzung:

HTTP	Bedingung
`400`	SIGNUP — die biometrische Identität ist bereits registriert (doppeltes Konto)
`400`	SIGNIN — die biometrische Identität ist nicht registriert (Konto existiert nicht)

Erfolgreiche Antwort:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Speichern Sie authToken — verwenden Sie es als Header x-console-authorization in allen nachfolgenden Human Dashboard API-Anfragen.

Phase 1 (Alternative) — Anmeldung per E-Mail-OTP

Verwenden Sie diesen Ablauf statt der Biometrie, wenn der Nutzer bereits ein Konto hat und sich lieber über einen einmaligen Code authentifizieren möchte, der an seine registrierte E-Mail gesendet wird. Die Registrierung wird per E-Mail-OTP nicht unterstützt — verwenden Sie für die Erstregistrierung den biometrischen Ablauf.

Schritt 1: Das OTP senden

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Hinweis

Die E-Mail muss zu einem bestehenden Konto gehören. Wird kein Konto gefunden, gibt Schritt 2 (Das OTP validieren) 404 Not Found zurück.

Antwort:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

Speichern Sie die sessionId. Ein 6-stelliger Code wird an die angegebene E-Mail-Adresse gesendet.

Schritt 2: Das OTP validieren

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	Bedingung
`200`	Der Code ist gültig — `authToken` ist vorhanden
`400`	Der Code ist falsch (`invalid otp code`)
`400`	OTP bereits verwendet, maximale Anzahl an Versuchen erreicht oder abgelaufen
`404`	E-Mail nicht registriert

Erfolgreiche Antwort:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

Speichern Sie authToken — verwenden Sie es als Header x-console-authorization in allen nachfolgenden Human Dashboard API-Anfragen.

Phase 2 — Organisation einrichten

Schritt 3: Ihre Organisation erstellen

Hinweis

Dieser Aufruf kann nur einmal erfolgen. Er stellt Ihren Tenant bereit und generiert Ihre branchId.

Jedes Land wird akzeptiert. Verwenden Sie den dreistelligen Code nach ISO 3166-1 alpha-3 (z. B. BRA, USA, MEX, DEU, IND). taxId ist für alle Länder optional.

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

Antwort:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Speichern Sie branchId — sie identifiziert Ihren Standard-Branch und wird bei der Verwaltung von Branches und Zugriffsschlüsseln verwendet.

Schritt 4: Einen Zugriffsschlüssel erstellen

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

Antwort:

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

Warnung

Der accessKey wird nur einmal zurückgegeben und kann nicht erneut abgerufen werden. Speichern Sie ihn sofort als HUMAN_TOKEN_ACCESS_KEY in Ihrem Secrets-Manager.

Dieser Wert ist der Header x-unico-accesskey, der in allen Human Token API-Anfragen verwendet wird.

Was Sie jetzt haben

Wert	Wo Sie ihn verwenden
`branchId`	Identifizierung Ihres Standard-Branches; Erstellung Branch-spezifischer Zugriffsschlüssel
`accessKey`	Header `x-unico-accesskey` in allen Human Token-Anfragen

Ihre Organisation verwalten

Organisation abrufen

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

Antwort:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

Organisation aktualisieren

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

Zugriffsschlüssel verwalten

Schlüssel auflisten (nur Metadaten — das Geheimnis wird nie zurückgegeben):

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

Einen Schlüssel rotieren (der alte Schlüssel wird sofort ungültig):

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Einen Schlüssel widerrufen (unumkehrbar):

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

Branches verwalten

Mit Branches können Sie die Konfiguration Ihrer Organisation (Name, Logo, erlaubte Domains) nach Produkt oder Umgebung aufteilen. Jeder Branch hat eigene Zugriffsschlüssel, sodass der Branch-Kontext automatisch aus dem in der Anfrage verwendeten Schlüssel ermittelt wird — branchId muss in CreateProcess nicht übergeben werden.

Einen Branch erstellen

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

Antwort:

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

Speichern Sie branchId — verwenden Sie sie beim Erstellen eines Branch-spezifischen Zugriffsschlüssels.

Einen Branch aktualisieren

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

Einen Branch-spezifischen Zugriffsschlüssel erstellen

Um einen Zugriffsschlüssel zu generieren, der auf einen bestimmten Branch beschränkt ist, fügen Sie branchId in den Request-Body ein:

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

Antwort:

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

Warnung

Der accessKey wird nur einmal zurückgegeben. Speichern Sie ihn sofort. Jede CreateProcess-Anfrage, die mit diesem Schlüssel authentifiziert wird, verwendet automatisch die damit verknüpfte Branch-Konfiguration.

Zwei Wege, Ihre Zugangsdaten einzurichten​

Über das Dashboard​

Basis-URLs​

Authentifizierungsmethoden​

Intent der biometrischen Anmeldung​

Phase 1 — Authentifizieren​

Schritt 1: Eine biometrische Anmeldesitzung starten​

Schritt 2: Abfragen, bis die Sitzung aufgelöst ist​

Phase 1 (Alternative) — Anmeldung per E-Mail-OTP​

Schritt 1: Das OTP senden​

Schritt 2: Das OTP validieren​

Phase 2 — Organisation einrichten​

Schritt 3: Ihre Organisation erstellen​

Schritt 4: Einen Zugriffsschlüssel erstellen​

Was Sie jetzt haben​

Ihre Organisation verwalten​

Organisation abrufen​

Organisation aktualisieren​

Zugriffsschlüssel verwalten​

Branches verwalten​

Einen Branch erstellen​

Einen Branch aktualisieren​

Einen Branch-spezifischen Zugriffsschlüssel erstellen​

Zwei Wege, Ihre Zugangsdaten einzurichten

Über das Dashboard

Basis-URLs

Authentifizierungsmethoden

Intent der biometrischen Anmeldung

Phase 1 — Authentifizieren

Schritt 1: Eine biometrische Anmeldesitzung starten

Schritt 2: Abfragen, bis die Sitzung aufgelöst ist

Phase 1 (Alternative) — Anmeldung per E-Mail-OTP

Schritt 1: Das OTP senden

Schritt 2: Das OTP validieren

Phase 2 — Organisation einrichten

Schritt 3: Ihre Organisation erstellen

Schritt 4: Einen Zugriffsschlüssel erstellen

Was Sie jetzt haben

Ihre Organisation verwalten

Organisation abrufen

Organisation aktualisieren

Zugriffsschlüssel verwalten

Branches verwalten

Einen Branch erstellen

Einen Branch aktualisieren

Einen Branch-spezifischen Zugriffsschlüssel erstellen