IP-Allowlist

Für jeden API-Schlüssel kann eine eigene IP-Allowlist festgelegt werden, sodass nur Anfragen von den angegebenen Quell-IP-Adressen diesen Schlüssel verwenden können.

Wann sie sinnvoll ist

Sie eignet sich für Produktionsdienste auf Servern mit fester ausgehender IP-Adresse. Wenn Ihre Anwendung über ein Heimnetz, ein Mobilfunknetz oder eine andere wechselnde Adresse zugreift, prüfen Sie zuerst, ob die ausgehende IP stabil ist — andernfalls können Sie sich selbst aussperren.

Einrichtung

Öffnen Sie /keys und öffnen Sie im Menü „…“ des gewünschten Schlüssels „IP-Allowlist“. Geben Sie die Einträge ein und speichern Sie.

Alternativ können Sie PATCH /api/v1/keys/:id mit einer angemeldeten Sitzung oder einem Management-API-Schlüssel verwenden:

1
2
3
4
5
6
7
8
9
10
11
12
13
PATCH https://api.bazaarlink.ai/v1/keys/KEY_ID
Authorization: Bearer sk-bl-YOUR_MANAGEMENT_KEY
Content-Type: application/json

{
"allowedCidrs": [
  "203.0.113.7",
  "198.51.100.0/24"
]
}

# Clear the allowlist and return to unrestricted access
{"allowedCidrs": []}

Format der Einträge

Geben Sie in der UI einen Wert pro Zeile ein. In der API kommen dieselben Werte in das Array `allowedCidrs`. Akzeptiert werden eine nackte IPv4-Adresse, ein IPv4-CIDR oder ein IPv6-Literal (nur exakter Abgleich).

1
2
3
203.0.113.7
198.51.100.0/24
2001:db8::1

Verhalten

Leer lassen (ein leeres []-Array senden) erlaubt alle Quell-IP-Adressen. Das ist der Standard; vorhandene Schlüssel behalten ihr bisheriges Verhalten.

Die Quell-IP wird aus dem Header `cf-connecting-ip` gelesen.

Ist die Liste nicht leer, kann die Quell-IP aber nicht ermittelt werden, wird die Anfrage abgelehnt (fail-closed).

⚠️ Wichtig: Abweisungen liefern nur einen allgemeinen 401

Eine Anfrage außerhalb der Liste — oder eine Anfrage, deren Quell-IP nicht ermittelt werden kann — erhält exakt denselben allgemeinen HTTP 401 wie bei einem ungültigen Schlüssel, ohne eigene Fehlermeldung. Das ist ein absichtliches Sicherheitsdesign, damit jemand mit einem erlangten Schlüssel nicht erkennt, dass eine Allowlist existiert. Der Nachteil: Eine falsch konfigurierte Liste sieht genau wie ein ungültiger Schlüssel aus und ist sehr schwer zu debuggen. Prüfen Sie vor dem Speichern, dass die ausgehende IP Ihres Servers bereits in der Liste steht.

⚠️ Wichtig: IPv6 unterstützt nur den exakten Zeichenfolgenabgleich

Für IPv6 wird keine Subnetzberechnung durchgeführt; die Adresse muss exakt mit der Zeichenfolge übereinstimmen. Wenn sich Ihre IPv6-Adresse ändert, können Sie ausgesperrt werden. CIDR-Bereiche /0–/32 werden nur für IPv4 unterstützt.

Wann Änderungen wirksam werden

Nach erfolgreichem PATCH oder Speichern in der UI leert die aktualisierende Instanz ihren Cache sofort. Unter normalen Bedingungen synchronisieren andere Instanzen spätestens innerhalb von etwa 15 Sekunden. Wenn das gemeinsame Redis vorübergehend nicht verfügbar ist, kann die Invalidierung zwischen Instanzen nicht sofort übertragen werden und bis zur Cache-TTL von einer Stunde verzögert sein.