--- title: Authentifizierung description: OAuth2 JWT Bearer Flow, der von allen IDCloud-Verträgen verwendet wird. Erfahren Sie, wie Sie Anmeldedaten abrufen, die JWT-Assertion erstellen und sie gegen ein Zugriffstoken austauschen. canonical: https://developer.unico.io/de/dual-api/developers/api-reference/authentication locale: de generated_by: markdown-export --- - [/de/](/de/) - [API-Referenz](/de/dual-api/developers/api-reference/) - Authentifizierung **Auf dieser Seite# Authentifizierung Alle IDCloud-APIs (Web & SDK- und API-Verträge) verwenden **OAuth2 mit JWT Bearer Grant Type** ([RFC 7523](https://datatracker.ietf.org/doc/html/rfc7523)). Sie generieren eine kurzlebige JWT-Assertion in Ihrem Back-End, tauschen sie gegen ein Bearer-Token aus und verwenden dieses Token bei jedem nachfolgenden Aufruf. Führen Sie dies niemals auf der Client-Seite durchDie JWT-Assertion muss ausschließlich in Ihrem **Back-End** generiert werden. Legen Sie Ihren privaten Schlüssel niemals in Front-End-Code, mobilen Apps, Repositories oder Logs offen. ### Anmeldedaten abrufen​ Bevor Sie Token generieren können, benötigen Sie ein von Unico bereitgestelltes **Dienstkonto**. Kontaktieren Sie den Unico-Support und geben Sie folgendes an: Name des Dienstkontos (max. 12 Zeichen) Name, E-Mail und Telefonnummer der verantwortlichen Person (nur Nummern aus Brasilien, USA oder Mexiko) Sie erhalten: Eindeutiger Kontoname Mandanten-ID (Tenant ID) Basis-JWT-Payload Private-Key-Datei (Format `.pem`) Ein Konto pro UmgebungVerwenden Sie separate Dienstkonten für **UAT** und **Produktion**. ### JWT-Assertion erstellen​ Die Assertion ist ein JWT im kompakten JWS-Format: `{Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}`. Header ``` { "alg": "RS256", "typ": "JWT"} ``` Payload ClaimWertHinweise`iss``@.iam.acesso.io`Wird mit Ihren Anmeldedaten bereitgestellt`aud``https://identityhomolog.acesso.io` (UAT) oder `https://identity.acesso.io` (Produktion)Muss mit dem Token-Endpoint-Host übereinstimmen`scope``*`Gewährt alle Berechtigungen`iat`Unix-Zeitstempel (Sekunden)Zeitpunkt der JWT-Ausstellung`exp``iat` + max 3600Darf `iat` nicht um mehr als 1 Stunde überschreiten ``` { "iss": "my-account@abc123.iam.acesso.io", "aud": "https://identity.acesso.io", "scope": "*", "iat": 1738086000, "exp": 1738089600} ``` Signature Signieren Sie Header + Payload mit **RS256** (RSA + SHA-256) und dem von Unico bereitgestellten privaten Schlüssel im Format `.pem`. Fügen Sie keine zusätzlichen Claims hinzuJedes Feld, das nicht oben aufgeführt ist (z. B. `sub`, `jti`, `nbf`), führt zu einem Fehler `1.2.22`. Verwenden Sie ausschließlich die angezeigten Claims. ### Token anfordern​ Der Token-Endpoint ist für beide Verträge identisch: UmgebungEndpoint**Produktion**`POST https://identity.acesso.io/oauth2/token`**UAT**`POST https://identityhomolog.acesso.io/oauth2/token` Request ParameterWert`Content-Type``application/x-www-form-urlencoded``grant_type``urn:ietf:params:oauth:grant-type:jwt-bearer``assertion`Ihr signiertes JWT cURLNode.jsPython``` curl -X POST https://identity.acesso.io/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \ -d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." ``` ``` import jwt from 'jsonwebtoken';import fs from 'fs';import qs from 'querystring';const privateKey = fs.readFileSync('./private-key.pem');const now = Math.floor(Date.now() / 1000);const assertion = jwt.sign( { iss: 'my-account@abc123.iam.acesso.io', aud: 'https://identity.acesso.io', scope: '*', iat: now, exp: now + 3600, }, privateKey, { algorithm: 'RS256' });const res = await fetch('https://identity.acesso.io/oauth2/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: qs.stringify({ grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer', assertion, }),});const { access_token, expires_in } = await res.json(); ``` ``` import timeimport jwt # PyJWTimport requestswith open("private-key.pem", "rb") as f: private_key = f.read()now = int(time.time())assertion = jwt.encode( { "iss": "my-account@abc123.iam.acesso.io", "aud": "https://identity.acesso.io", "scope": "*", "iat": now, "exp": now + 3600, }, private_key, algorithm="RS256",)response = requests.post( "https://identity.acesso.io/oauth2/token", data={ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion, },)token_data = response.json()access_token = token_data["access_token"] ``` Response ``` { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600} ``` FeldTypBeschreibung`access_token`stringJWT-Zugriffstoken. Verwenden Sie es als `Authorization: Bearer ` bei allen API-Aufrufen.`expires_in`integerAblaufzeit in Sekunden. Beispiel: `3600`.`token_type`stringImmer `Bearer`. ### Token verwenden​ Fügen Sie das Token dem `Authorization`-Header jeder API-Anfrage hinzu. Der Header ist für beide Verträge identisch — was sich unterscheidet, ist der **Host und Pfad** der aufgerufenen API: VertragProduktions-HostUAT-Host**Web & SDK**`https://api.idcloud.unico.app``https://api.idcloud.uat.unico.app`**API**`https://api.id.unico.app``https://api.id.uat.unico.app` **Web & SDK** — `Authorization` ist der einzige erforderliche Auth-Header: ``` curl -X POST https://api.idcloud.unico.app/client/v1/process \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ ... }' ``` **API** — `Authorization` wird zusammen mit dem `APIKEY`-Header verwendet: ``` curl -X POST https://api.id.unico.app/processes/v1 \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "APIKEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ ... }' ``` ### Token erneuern​ Token laufen nach 3600 Sekunden ab. Implementieren Sie eine proaktive Erneuerung in Ihrem Back-End: Verfolgen Sie `expires_in` aus der Token-Antwort und speichern Sie den Ablaufzeitstempel. Fordern Sie ein neues Token an, **wenn noch 10 Minuten oder weniger** bis zum Ablauf verbleiben. Warten Sie in der Produktionsumgebung nie auf ein `401`, bevor Sie eine Erneuerung auslösen. ### API-Referenz​ Die vollständige OpenAPI-Spezifikation für den Token-Endpoint ist in [`authentication.yaml`](/de/assets/files/authentication-1d221f9a7230435e9c390ba98dac7321.yaml) verfügbar. MethodePfadBeschreibung`POST``/oauth2/token`Tauscht eine signierte JWT-Assertion gegen ein Bearer-Zugriffstoken aus ### Fehlercodes​ CodeBeschreibungMaßnahme`1.0.1`Die in der `iss`-Bildung angegebene ID ist falschÜberprüfen Sie, ob das `iss`-Feld mit der Mandanten-ID übereinstimmt, die bei der Generierung des privaten Schlüssels angegeben wurde`1.0.14`Anwendung ist nicht aktivPrüfen Sie mit dem Projektmanager, ob die verwendete Anwendung aktiv ist`1.1.1`Der Parameter `scope` wurde nicht angegebenFügen Sie `"scope": "*"` zu Ihrem JWT-Payload hinzu`1.2.4`JWT-Assertion ungültigDie JWT-Assertion ist nicht mehr gültig. Zwei mögliche Ursachen: (a) der aktuelle Zeitpunkt liegt nach `exp` (JWT tatsächlich abgelaufen — generieren Sie für jede Token-Anfrage eine neue Assertion); oder (b) `exp` überschreitet `iat + 3600` (Gültigkeitsdauer zu lang — begrenzen Sie `exp` auf `iat + 3600`).`1.2.5`JWT-Validierung fehlgeschlagenDas JWT kann nicht validiert werden. Überprüfen Sie die Parameter und stellen Sie sicher, dass es mit RS256 und dem richtigen privaten Schlüssel signiert wurde`1.2.6`Privater Schlüssel ist nicht mehr gültigDer zum Signieren des JWT verwendete private Schlüssel ist nicht mehr akzeptiert. Fordern Sie neue Anmeldedaten für das Konto an`1.2.7`JWT bereits verwendetDas JWT wird nicht mehr akzeptiert, da es bereits verwendet wurde. Generieren Sie für jede Token-Anfrage eine neue Assertion`1.2.11`Konto ist nicht aktivDas verwendete Konto ist nicht aktiv`1.2.14`Konto verfügt nicht über die erforderlichen BerechtigungenDas verwendete Konto besitzt nicht die erforderlichen Berechtigungen`1.2.18`Konto vorübergehend gesperrtDas Konto wurde vorübergehend gesperrt, da die Anzahl ungültiger Authentifizierungsversuche überschritten wurde`1.2.19`Nicht autorisierte BenutzerverkörperungDas JWT enthält einen `sub`-Claim, der auf ein Konto verweist, das nicht zur Verkörperung autorisiert ist. Entfernen Sie den `sub`-Claim aus dem Payload.`1.2.20`JWT-Dekodierung fehlgeschlagenDas JWT konnte nicht dekodiert werden. Überprüfen Sie das Token-Format und stellen Sie sicher, dass es mit RS256 signiert wurde.`1.2.21`Falscher privater Schlüssel / Authentifizierung fehlgeschlagenDie JWT-Signatur konnte für kein bekanntes Schlüsselpaar dieses Kontos verifiziert werden. Stellen Sie sicher, dass Sie den richtigen `.pem`-Schlüssel für dieses Dienstkonto und diese Umgebung verwenden.`1.2.22`Nicht erlaubte Felder im PayloadDas JWT enthält zusätzliche Payload-Felder, die nicht erlaubt sind. Entfernen Sie alle Claims, die nicht in dieser Anleitung aufgeführt sind (z. B. `sub`, `jti`, `nbf`). Hinweis: Falls ein `sub`-Claim enthalten war und stattdessen Fehler `1.2.19` aufgetreten ist, hat dieser Fehler Vorrang.`1.3.1`IP-ZugriffsbeschränkungIhre IP befindet sich nicht auf der Zulassungsliste für dieses Konto`1.3.2`Zeitbasierte ZugriffsbeschränkungDie Anfrage liegt außerhalb des erlaubten Zeitfensters für dieses Konto ### Nächste Schritte​ [Umgebungen](/de/dual-api/developers/api-reference/environments) — Sandbox vs. Produktions-Hosts [Web & SDK — Prozess erstellen](/de/dual-api/developers/api-reference/web-sdk/post-process) — erster Aufruf nach der Authentifizierung [API — Prozess erstellen](/de/dual-api/developers/api-reference/api/post-processes) — erster Aufruf nach der Authentifizierung [SSO / SAML](/de/dual-api/developers/api-reference/sso-saml) — authentifizieren Sie Ihre Benutzer mit Ihrem eigenen Identity Provider in Unicos Produktportalen, anstelle des oben beschriebenen Server-zu-Server-Flows Zuletzt aktualisiert am 8. Okt. 2026**