Dedizierte Gateways

Benutzer des Nirvana-Plans erhalten ein privates IPFS-Gateway unter einer einzigartigen Subdomain. Dieses Gateway liefert nur Dateien aus, die an Ihr Konto gepinnt sind — es werden keine CIDs anderer Benutzer oder des öffentlichen IPFS-Netzwerks aufgelöst.

Ihre Gateway-URL

Ihre Gateway-URL wird auf Ihrer Gateway-Seite angezeigt und vom /user/profile-Endpunkt zurückgegeben:

https://<your-slug>.gw.ipfs.ninja/ipfs/<CID>

Zugriffsmodi

Modus	Verhalten
Offen (Standard)	Jeder mit Ihrer Gateway-URL und dem CID kann auf Ihre Dateien zugreifen. Kein Token erforderlich.
Token erforderlich	Anfragen müssen ein Gateway-Token über den ?token=gwt_...-Abfrageparameter oder den X-Gateway-Token-Header enthalten.

Limits

• 50 GB/Monat Gateway-Bandbreite im Nirvana-Plan enthalten
• Wenn das Bandbreitenlimit erreicht ist, geben Gateway-Anfragen 429 zurück, bis der nächste Monat beginnt
• Die Speichernutzung wird am Ersten jedes Kalendermonats zurückgesetzt
• Es werden nur CIDs ausgeliefert, die an Ihr Konto gepinnt sind — Anfragen für andere CIDs geben 403 zurück

TIP

Das öffentliche Gateway unter ipfs.ninja/ipfs/ bleibt in allen Plänen verfügbar und liefert jeden CID ohne Authentifizierung aus.

Gateway-Einstellungen

Konfigurieren Sie Zugriffskontrollen für Ihr dediziertes Gateway.

Einstellungen aktualisieren

PUT /gateway-settings

Parameter	Typ	Erforderlich	Beschreibung
tokenRequired	boolean	Nein	Gateway-Token-Pflicht aktivieren/deaktivieren.
ipWhitelist	string[]	Nein	Array von IP-Adressen, die zugelassen werden sollen. Max. 100. Ein leeres Array entfernt die Whitelist.
allowedOrigins	string[]	Nein	Array erlaubter Origins für Browseranfragen. Max. 100. Muss HTTPS-Format verwenden (z. B. https://myapp.com). Ein leeres Array erlaubt alle Origins.

Beispiele

# Token-Pflicht-Modus aktivieren
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tokenRequired": true}'

# IP-Whitelist setzen
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": ["203.0.113.1", "198.51.100.0"]}'

# IP-Whitelist löschen (alle IPs erlauben)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": []}'

# Auf bestimmte Origins beschränken
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": ["https://myapp.com", "https://staging.myapp.com"]}'

# Origin-Einschränkungen entfernen (alle Origins erlauben)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": []}'

Origin-Einschränkungen

Wenn allowedOrigins konfiguriert ist, werden nur Browseranfragen von den aufgelisteten Origins zugelassen. Das Gateway prüft die Origin- und Referer-Header eingehender Anfragen.

• Wenn die Liste leer ist (Standard), werden alle Origins zugelassen.
• Wenn Origins angegeben sind, werden Anfragen mit einem Origin- oder Referer-Header, der keinem Eintrag entspricht, mit einer 403-Antwort abgelehnt.
• Nicht-Browser-Anfragen ohne Origin-Header (wie serverseitige Abrufe oder curl) werden ohne Einschränkung durchgelassen.

Dies ist nützlich, um Gateway-Inhalte in Ihre Webanwendung einzubetten und gleichzeitig zu verhindern, dass andere Websites Ihre Dateien per Hotlinking verwenden.

Gateway-Token

Gateway-Token (Präfix gwt_) sind schreibgeschützt und können sicher in Frontend-Anwendungen eingebettet werden. Im Gegensatz zu API-Schlüsseln kann ein Gateway-Token nur über Ihr dediziertes Gateway auf Dateien zugreifen — er kann nicht hochladen, löschen oder Ihr Konto verwalten.

Fähigkeit	API-Schlüssel (bws_)	Gateway-Token (gwt_)
Dateien hochladen / löschen	Ja	Nein
Dateien auflisten / Metadaten abrufen	Ja	Nein
Dateien über Gateway lesen	Nein	Ja
Sicher im Frontend einbettbar	Nein	Ja

Gateway-Token erstellen

POST /gateway-tokens

Parameter	Typ	Erforderlich	Beschreibung
name	string	Nein	Bezeichnung für den Token (z. B. "Frontend"). Standard ist "Default".

Antwort 201 Created

{
  "token": "gwt_a1b2c3d4e5f6789012345678abcdef01",
  "tokenPrefix": "gwt_a1b2c3d4",
  "tokenName": "Frontend",
  "createdAt": 1711036800000
}

WARNING

Der vollständige Token wird nur einmal bei der Erstellung zurückgegeben. Speichern Sie ihn sicher.

Gateway-Token auflisten

GET /gateway-tokens

[
  {
    "tokenPrefix": "gwt_a1b2c3d4",
    "tokenName": "Frontend",
    "createdAt": 1711036800000
  }
]

Gateway-Token löschen

DELETE /gateway-tokens/:prefix

Parameter	Typ	Erforderlich	Beschreibung
prefix	string	Ja	Das Token-Präfix zum Löschen (z. B. "gwt_a1b2c3d4").

Einen Gateway-Token verwenden

Wenn Ihr Gateway den Token-Pflicht-Modus aktiviert hat, übergeben Sie den Token als Abfrageparameter oder Header:

# Abfrageparameter
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# Oder Header
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"