Zum Inhalt

Authentifizierung

🤖 Erklären mit KI

Um die Integrität und Sicherheit des gesamten Datentransfers zu gewährleisten, implementiert 4Geeks die API-Key-Authentifizierung als primären Architekturstandard für die Autorisierung eingehender Serviceanfragen. Gemäß diesem Protokoll muss jede programmgesteuerte Interaktion von einem eindeutigen, gültigen API-Key begleitet werden; falls diese Anmeldedaten nicht bereitgestellt werden, führt dies zu einer sofortigen Ablehnung der Autorisierung, um sensible Systemressourcen zu schützen. Diese Anmeldedaten werden über das HTTP Basic Authentication Framework übermittelt, wie es im Branchenstandard RFC 7617 strikt definiert ist. Dies erfordert, dass der Schlüssel im Request-Header gemäß den spezifischen Formatierungskonventionen übergeben wird, die in der folgenden technischen Dokumentation beschrieben sind.

Authorization: Basic <base64_encoded_credentials>

Dabei ist <base64_encoded_credentials> Ihr API-Key, gefolgt von einem Doppelpunkt (:) und dann Base64-kodiert.

Schritt-für-Schritt-Kodierung

1. Ihr API-Key:

sk_test_51O62xYzAbcDef123

2. Doppelpunkt nach dem Schlüssel hinzufügen: 

sk_test_51O62xYzAbcDef123:

3. In Base64 kodieren: 

c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

4. Zum Authorization-Header hinzufügen: 

Authorization: Basic c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

Code-Beispiele

curl -X GET 'http://api.4geeks.io/v1/customers/' \
  -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.get(
    'http://api.4geeks.io/v1/customers/',
    headers={
        'Authorization': f'Api-Key {api_key}'
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";

fetch("http://api.4geeks.io/v1/customers/", {
    method: "GET",
    headers: {
        Authorization: `Api-Key ${apiKey}`,
    },
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

export class CustomerService {
    private apiKey = "sk_test_51O62xYzAbcDef123";

    constructor(private http: HttpClient) {}

    getCustomers() {
        const headers = new HttpHeaders({
            Authorization: `Api-Key ${this.apiKey}`,
        });

        return this.http.get("http://api.4geeks.io/v1/customers/", { headers });
    }
}

Fehlerbehandlung

400 Bad Request

Tritt auf, wenn in der Anfrage erforderliche Felder fehlen oder das Format ungültig ist.

Beispiel:

{
    "message": {
        "code": 400,
        "title": "Ungültige Anfrage",
        "content": "Bitte geben Sie ein gültiges 'type'-Feld an: 'test' oder 'live'.",
        "type": "danger"
    }
}

Ursachen:

  • Fehlendes type-Feld in einer PATCH-Anfrage
  • Ungültiger type-Wert (muss "test" oder "live" sein)

Lösung: Fügen Sie {"type": "test"} oder {"type": "live"} in den Request-Body ein.

401 Unauthorized

Authentifizierung fehlgeschlagen. Der API-Key ist ungültig, fehlt oder ist fehlerhaft formatiert.

Beispiele:

  1. Fehlender Authorization-Header (Bearer-Token)
Anfrage: GET /v1/auth/api-keys/ (ohne Authorization-Header)
Antwort:
{
  "detail": "Authentifizierungsdaten wurden nicht bereitgestellt."
}
  1. Schlüssel nicht gefunden
Anfrage: Authorization-Header mit nicht existierendem Schlüssel
Antwort:
{
    "detail": "Der angegebene Token ist für keinen Tokentyp gültig",
    "code": "token_not_valid",
    "messages": [
        {
            "token_class": "AccessToken",
            "token_type": "access",
            "message": "Token ist ungültig oder abgelaufen"
        }
    ]
}

Lösungen:

  • Überprüfen Sie, ob Sie den Header Authorization: Bearer <Bearer_Token> hinzugefügt haben
  • Überprüfen Sie, ob der Schlüssel vor kurzem rotiert wurde
  • Testen Sie mit Postman, um das Problem einzugrenzen

404 Not Found

Es existieren keine API-Keys für diesen Benutzer.

Beispiel:

{
    "code": 404,
    "title": "API-Keys nicht gefunden",
    "content": "Keine API-Keys für diesen Benutzer gefunden. Bitte kontaktieren Sie den Support.",
    "type": "warning"
}

Lösung: Kontaktieren Sie den Support, um API-Keys für Ihr Konto zu initialisieren.

Best Practices für die Sicherheit

Schützen Sie Ihre Schlüssel

  • Speichern Sie Schlüssel in Umgebungsvariablen, niemals im Code
  • Checken Sie Schlüssel nicht in die Versionsverwaltung ein
  • Verwenden Sie .env-Dateien zusammen mit .gitignore
  • Rotieren Sie Schlüssel alle 3-6 Monate
  • Generieren Sie Schlüssel sofort neu, wenn sie offengelegt wurden

Beispiel für Umgebungsvariablen:

# .env
API_KEY_TEST=sk_test_51O62xYzAbcDef123
API_KEY_LIVE=sk_live_xYzAbcDef123456789
API_URL=http://api.4geeks.io

Anwendung:

import os
api_key = os.getenv('API_KEY_TEST')

Fehlerbehebung

Problem: 401 Unauthorized „Ungültiges API-Key-Format“

Ursachen:

  • Der API-Key ist unvollständig oder abgeschnitten
  • Die Base64-Kodierung enthält den Doppelpunkt (:) nicht
  • Zusätzliche Leerzeichen im Schlüssel oder Header
  • Der Schlüssel wurde vor kurzem rotiert

Lösungen:

  1. Kopieren Sie den Schlüssel erneut:
    • Gehen Sie im Dashboard zu Einstellungen → API-Keys
    • Kopieren Sie den vollständigen Schlüssel sorgfältig

  2. Überprüfen Sie die Base64-Kodierung:

  3. Mit Postman testen:

    • Erstellen Sie eine neue Anfrage
    • Authorization → Basic Auth
    • Username: [Ihr vollständiger Schlüssel]
    • Password: [leer lassen]
    • Senden

Problem: Schlüssel funktioniert nach Rotation nicht mehr

Ursache: Sie haben den Schlüssel rotiert, aber Ihre Anwendung verwendet noch den alten.

Lösung:

  1. Gehen Sie zu Einstellungen → API-Keys
  2. Kopieren Sie den neuen Schlüssel
  3. Aktualisieren Sie Ihre .env oder Konfiguration
  4. Starten Sie Ihre Anwendung neu

Problem: 404 „API-Keys nicht gefunden“

Ursache: Für Ihr Konto sind keine API-Keys initialisiert.

Lösung: Kontaktieren Sie den Support, um Ihre API-Keys zu initialisieren.

Häufig gestellte Fragen (FAQ)

F: Kann ich mehrere API-Keys haben? A: Nein. Sie haben genau einen Test-Key und einen Live-Key. Verwenden Sie den Rotations-Endpunkt, um sie neu zu generieren.

F: Was passiert, wenn mein Live-Key offengelegt wird? A: Rotieren Sie ihn sofort über das Dashboard. Der offengelegte Schlüssel wird innerhalb einer Minute ungültig.

F: Kann ich denselben Schlüssel für Test und Live verwenden? A: Nein. Test- und Live-Keys sind getrennt. Verwenden Sie in der Entwicklung immer Test-Keys.

F: Muss ich meinen API-Key aktualisieren? A: Anders als JWT-Token laufen API-Keys nicht ab. Sie bleiben gültig, bis Sie sie rotieren.

F: Kann ich API-Keys mit Webhooks verwenden? A: Nein. Webhooks werden von unseren Servern an Ihren Endpunkt gesendet. Sie authentifizieren den Webhook über Signaturen, nicht über API-Keys.