API-Authentifizierung und Bearer-Token

Wie die Authentifizierung funktioniert

1. Registrieren Sie sich und melden Sie sich bei Ihrem Quote3D-Konto an.
2. Generieren Sie ein API-Token unter dem Reiter "Tokens" in Ihrem Dashboard.
3. Fügen Sie das Token in Ihre API-Anfragen ein. Es werden sowohl `Authorization: Bearer` als auch `X-API-Token` unterstützt:
   Authorization: Bearer YOUR_TOKEN_HERE
4. Der Server verifiziert Ihr Token und gewährt Zugriff, wenn es gültig und nicht abgelaufen ist.

Token-Bereiche

Der Bereich eines Tokens bestimmt, welche Endpunkte es erreichen kann. Sie wählen den Bereich beim Erstellen des Tokens aus, und Sie können ihn auf der Seite „Tokens“ in Ihrem Dashboard einsehen.

• Vollzugriff – der Standard für ein serverseitiges Token. Es erreicht jeden Endpunkt, den Ihr Tarif zulässt.
• Widget – der Bereich für ein Token, das Sie in eine Storefront einbetten. Er ist auf das beschränkt, was das einbettbare Widget benötigt, und kann nicht auf Webhooks, Kontodaten, Analysen, Nutzung oder Kontingente zugreifen.

Ein Aufruf eines Endpunkts außerhalb des Token-Bereichs wird mit 403 abgelehnt, obwohl das Token selbst gültig ist. Falls eine Anfrage mit 403 fehlschlägt, während dasselbe Token an anderer Stelle funktioniert, überprüfen Sie zuerst dessen Bereich.

Token-Lebenszyklus

• Der Wert eines Tokens wird nur einmal bei der Erstellung angezeigt. Er kann danach nicht wiederhergestellt werden – speichern Sie ihn sofort in Ihrem Secret Manager. Wenn Sie ihn verlieren, rotieren Sie den Token, um einen neuen Wert zu erhalten.
• Tokens können mit einem Ablaufdatum erstellt werden. Ein abgelaufener Token funktioniert nicht mehr und gibt einen 401-Fehler zurück; das Dashboard zeigt das Ablaufdatum jedes Tokens an.
• Das Rotieren eines Tokens generiert einen neuen Wert und macht den alten sofort ungültig. Stellen Sie den neuen Wert bereit, bevor Sie rotieren, da laufende Anfragen, die den alten Token verwenden, sofort fehlschlagen.
• Ein Token kann auf eine Liste von IP-Adressen beschränkt werden. Anfragen von jeder anderen Adresse werden mit 403 abgelehnt – eine häufige Überraschung nach dem Umzug eines Servers oder dem Ändern eines NAT-Gateways.
• Ihr Tarif begrenzt die Anzahl der Token, die Sie besitzen können. Kostenlose Tarife erlauben einen Server-Token und einen Widget-Token.

Wenn die Authentifizierung fehlschlägt

Eine abgelehnte Anfrage gibt den Standard-Fehler-Envelope mit success: false und einer kurzen Nachricht zurück. Verzweigen Sie anhand des HTTP-Statuscodes statt anhand des Nachrichtentextes, der umformuliert werden kann.

{
  "success": false,
  "error": "API token has expired"
}

• 401 — das Token fehlt, ist falsch formatiert, abgelaufen oder widerrufen. Überprüfen Sie den Header-Namen und ob der Wert beim Kopieren gekürzt wurde.
• 403 — das Token ist gültig, aber für diesen Aufruf nicht zulässig. Die üblichen Ursachen sind eine Scope-Einschränkung oder eine IP-Allowlist, die den Aufrufer nicht enthält.

Token-Format

Quote3D-Token sind Bearer-Style-API-Anmeldeinformationen. Clients sollten diese als undurchsichtige Geheimnisse behandeln und es vermeiden, von der internen Struktur des Tokens abhängig zu sein.

Ein JWT besteht aus drei Teilen:

1. Header: Gibt den Signatur-Algorithmus und den Token-Typ an.
2. Payload: Enthält Benutzerdaten und Ansprüche (wie Benutzer-ID, E-Mail und Ablaufzeit).
3. Signatur: Verifiziert, dass der Token nicht manipuliert wurde.

Ein JWT sieht wie folgt aus:

Für Integrationen gilt eine einfache Regel: Speichern Sie das Token sicher, senden Sie es mit jeder Anfrage und vermeiden Sie das Parsen oder Offenlegen in Client-Code, es sei denn, die Integration erfordert explizit ein clientseitiges Token.

Beispiel: Verwendung Ihres Tokens

Hier erfahren Sie, wie Sie Ihr Token mit curl verwenden können. Verwenden Sie einen Authentifizierungsheader-Stil konsistent:

Oder fügen Sie im API-Spielplatz Ihr Token in das Autorisierungsmodal (Schloss-Symbol) ein, um Ihre Sitzung zu authentifizieren. Sie können auch X-API-Token in benutzerdefinierten Integrationen verwenden, wenn dieser Header besser geeignet ist.