---
title: Authentifizierung
description: So authentifizieren Sie sich beim Human Dashboard, richten Ihre Organisation ein und generieren den x-unico-accesskey, der in jeder Human Token API-Anfrage verwendet wird.
canonical: https://developer.unico.io/de/human-token/get-started/authentication
locale: de
generated_by: markdown-export
---

- [/de/](/de/)
- Erste Schritte
- Authentifizierung

**Auf dieser Seite# Authentifizierung

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](https://dashboard.unico.app) erledigt werden — ganz ohne API-Aufrufe.
OptionWann 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](https://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](/de/human-token/get-started/environments) aufgeführt ist.
UmgebungAPIBasis-URLProduktionHuman 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:
MethodeEndpunktWann 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 verwendenFeld `email`Feld `name``LOGIN_INTENT_SIGNUP`Erstregistrierung — Erstellen eines neuen Kontos**Erforderlich****Erforderlich**`LOGIN_INTENT_SIGNIN`Wiederkehrender Nutzer — das Konto existiert bereitsNicht verwendetNicht verwendet(weggelassen)Wird als `LOGIN_INTENT_SIGNIN` behandeltNicht verwendetNicht 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": "admin@acme.com",    "name": "Jane Doe"  }'
```

Eindeutigkeit der E-MailWenn 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:**
HTTPBedingung`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": "admin@acme.com"  }'
```

HinweisDie 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}
```

HTTPBedingung`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​

HinweisDieser 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](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) (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": "admin@acme.com",    "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": "admin@acme.com",    "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​

WertWo 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": "admin@acme.com",    "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": "admin@acme.com",    "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.Zuletzt aktualisiert am 21. Okt. 2026**