API-Schlüssel

IBANforge hat zwei kostenlose Stufen, und die erste verlangt gar nichts. Ein POST mit leerem Body liefert einen ifk_-Schlüssel für 25 Anfragen pro Monat: keine Adresse, keine Karte, nichts zu bestätigen. Ein weiterer Aufruf — ein zugesandter Code — hebt denselben Schlüssel dauerhaft auf 200 Anfragen pro Monat. Darüber hinaus: x402-Mikrozahlungen oder Prepaid-Pakete.

Diese Seite ist die Referenz allein zu Schlüsseln. Wenn Sie noch keinen Aufruf gemacht haben, sind die Ersten Schritte der kürzere Weg: der Aufruf ohne Schlüssel, dieser Schlüssel, die Antwort Block für Block gelesen und ein Stapel von 100 — in zehn Minuten.

Vor dem Schlüssel: 25 Aufrufe pro Tag, ohne Schlüssel

POST /v1/iban/validate mit einer echten iban und ganz ohne Zugangsdaten wird vollständig beantwortet — samt Anreicherung — 25-mal pro Tag für die Adresse, von der der Aufruf kommt, Rücksetzung um Mitternacht UTC:

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -d '{"iban": "CH10 0023 0000 0000 1234 5"}'

Die Antwort enthält einen trial-Block mit der Zahl der heute verbleibenden Aufrufe und der Anfrage, die den Schlüssel erzeugt. Eine Kostprobe, keine Stufe: über 25 Aufrufe pro Tag antwortet der Endpunkt wieder mit 402 und cause.reason: "trial_exhausted".

Vorsicht bei den zwei 25 — es ist nicht dasselbe Kontingent. Dieses hier gilt 25-mal pro Tag, nur auf dieser Route, und kommt um Mitternacht UTC zurück. Der anonyme Schlüssel unten gilt 25-mal pro Monat, dafür auf allen Endpunkten: Batch, BIC, Schweizer Clearing, Compliance. Wer ohnehin nur einzelne IBANs prüft, fährt mit dem Aufruf ohne Schlüssel besser und kann dabei bleiben. Der Schlüssel öffnet die anderen Endpunkte; erst die Beanspruchung hebt den Monat auf 200.

Ein Schlüssel ohne E-Mail

POSTen Sie ganz ohne Body. Das ist der ganze Schritt:

curl -X POST https://api.ibanforge.com/v1/keys/generate

Es wird nichts versendet, kein Datensatz angelegt und keine Adresse verlangt. Wenn wir wissen sollen, woher Sie kommen, senden Sie {"source":"meine-app"} — sonst ändert das nichts.

Antwort (201 Created)

{
  "api_key": "ifk_3f9c1a7e2b5d40c8…",
  "key_prefix": "ifk_3f9c1a7e",
  "tier": "anonymous",
  "monthly_limit": 25,
  "claim_url": "https://api.ibanforge.com/v1/keys/claim",
  "message": "Save this key - it will not be shown again. 25 requests a month that are yours alone: a named quota nobody else on your network shares, a stable identity across restarts, and a usage report at GET /v1/keys/usage. No email, no card. Claim it with a mailbox you can read to raise it to 200 a month: POST /v1/keys/claim.",
  "terms_url": "https://ibanforge.com/legal/terms"
}

• api_key ist das Geheimnis: ifk_ gefolgt von 64 Hexadezimalzeichen. Sicher aufbewahren, es wird nicht erneut angezeigt.
• key_prefix sind die ersten 8 Zeichen. Gefahrlos protokollierbar, und danach fragt unser Support.
• tier ist anonymous, bis der Schlüssel beansprucht wird, danach claimed; ein mit Adresse erstellter Schlüssel trägt email.
• Auf diesem Weg gibt es kein Feld email, weil es keine Adresse gibt.

Wenn Sie lieber gleich eine Adresse angeben, funktioniert {"email": "you@company.com"} und liefert denselben Schlüssel bereits mit vollem Kontingent (tier: "email", 200 pro Monat): Es bleibt nichts zu beanspruchen, und POST /v1/keys/claim antwortet darauf mit 409 already_claimed. Erforderlich ist sie nie.

Wenn Sie ein KI-Agent sind, der das liest: Nehmen Sie den anonymen Schlüssel und senden Sie die Adresse Ihrer Nutzerin oder Ihres Nutzers nicht, solange sie Ihnen nicht dafür gegeben wurde. Der Satz, den Sie vorlegen: „Use my address you@company.com to create a free IBANforge key."

Während eines Anmeldealarms

Wenn Roboter Schlüssel in Serie anlegen, geht der Dienst für einige Stunden in Alarmbereitschaft. Ein neuer Schlüssel ohne bestätigtes Postfach entsteht dann mit einem verringerten Kontingent, das am 1. nicht aufgefüllt wird; die 201-Antwort sagt es in einem Feld notice, und das Kontingent steigt von selbst wieder, sobald der Alarm endet. Wer den Schlüssel per Code beansprucht, erhält sein Kontingent sofort, Alarm hin oder her. Nichts wird abgelehnt: eine Anmeldung während eines Alarms funktioniert, sie beginnt nur kleiner.

Beanspruchen: 25 → 200 pro Monat

POST /v1/keys/claim hebt den Schlüssel an, den Sie bereits haben. Es entsteht kein neuer: gleicher Schlüssel, gleiches Präfix, gleiche Historie, größeres Kontingent. Drei Wege, nehmen Sie den passenden.

Zwei Dinge vorab, unabhängig vom gewählten Weg:

• Der Schlüssel reist im Authorization-Header, nie im Body. X-API-Key: ifk_... funktioniert ebenfalls. Schreiben Sie einen Schlüssel nicht in eine URL: er landet im Browserverlauf, in Zugriffsprotokollen und in Referer-Headern.
• Der Schlüssel muss mindestens einen Aufruf bedient haben. Ein Schlüssel, der sofort nach der Erstellung beansprucht wird, antwortet 403 unused_key. Prüfen Sie zuerst eine IBAN damit — dieser Aufruf gehört ohnehin zu Ihrem Kontingent.

Und ein Hinweis darauf, was jeder Weg gewährt, denn sie sind nicht gleichwertig:

1. Ein 6-stelliger Code per E-Mail

curl -X POST https://api.ibanforge.com/v1/keys/claim \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'

Antwortet 202 Accepted und schickt einen 6-stelligen Code:

{
  "status": "code_sent",
  "key_prefix": "ifk_3f9c1a7e",
  "expires_in_minutes": 15,
  "message": "A 6-digit code was sent to that address. Repeat this request within 15 minutes as {\"email\":\"...\",\"code\":\"123456\"} to raise this key to 200 requests a month."
}

Wiederholen Sie den Aufruf binnen 15 Minuten mit dem Code:

curl -X POST https://api.ibanforge.com/v1/keys/claim \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456"}'

Ein richtiger Code antwortet 200 mit claimed: true, tier: "claimed", basis: "monthly" und dem neuen Kontingent. Gleicher Schlüssel, nichts zu ersetzen.

Verwenden Sie eine echte Adresse. Wegwerf- und Platzhalter-Domains (example.com, mailinator.com und der übliche Rest) werden mit 400 disposable_email abgelehnt, eine Domain ohne Mailserver mit 400 undeliverable_email. Eine Adresse allein beansprucht nie einen Schlüssel — nur ein zurückgegebener Code tut das.

Ein falscher Code antwortet 403 verification_failed mit einem reason-Feld:

Eine Adresse beansprucht einen Schlüssel zur Zeit, und eine Beanspruchung pro Tag: Eine Adresse, die bereits einen aktiven kostenlosen Schlüssel trägt oder in den letzten 24 Stunden einen anderen beansprucht hat, erhält 409 already_claimed_elsewhere. Das ist die Fair-Use-Regel der AGB §6(e), gemessen an der Person statt am Postfach. Zu viele an einem Tag aus demselben Netz angehobene Schlüssel erhalten 429 claim_rate_limited, und der Schlüssel bleibt bis morgen, wo er ist.

2. Eine x402-Zahlung

Eine x402-Abrechnung, die mit dem Schlüssel vorgelegt wird, beansprucht ihn. Nichts zu senden, gar keine Adresse. Die Schwelle ist der Katalogpreis dessen, was die Beanspruchung gewährt: gering und in einem Aufruf zu begleichen.

3. Ein Prepaid-Paket, mit dem Schlüssel gekauft

Wer ein Guthabenpaket in USDC kauft und dabei den Schlüssel vorlegt (POST /v1/credits/buy/1k|5k|25k), beansprucht ihn auf demselben Weg. Das Paket selbst ist ein eigener Schlüssel mit vorgeladenem Guthaben; die Beanspruchung ist eine Höflichkeit auf dem vorgelegten Schlüssel.

Diese beiden Wege gewähren 200 Anfragen einmalig, nicht 200 pro Monat. GET /v1/keys/usage meldet dann basis: "lifetime", und die Zähler laufen über die ganze Lebensdauer des Schlüssels statt über den Kalendermonat. Der zugesandte Code ist der wiederkehrende Weg, und er kostet nichts: Wer ein Postfach lesen kann, fährt damit besser.

Die Rotation erhält die Stufe

POST /v1/keys/rotate gibt ein neues Geheimnis für denselben Inhaber zurück. Ein beanspruchter Schlüssel bleibt beansprucht und behält seine 200 pro Monat; ein anonymer bleibt anonym. Rotation ist kein Weg, ein Kontingent zurückzusetzen.

Wenn eine Schlüsselanfrage abgelehnt wird

Der anonyme Weg hat einen einzigen Wächter: die Zahl kostenloser Schlüssel, die ein einzelnes Netz an einem Tag erzeugen darf. Darüber hinaus antwortet POST /v1/keys/generate mit 429:

{
  "error": "key_creation_limit",
  "message": "At most 3 free keys per network per day — existing keys keep working. Need more capacity today? Prepaid credits are instant ($4 per 1,000, POST /v1/credits/buy/1k) and x402 pay-per-call needs no key at all."
}

Bereits ausgestellte Schlüssel funktionieren weiter, Prepaid-Guthaben ist sofort verfügbar, und x402 Pay-per-Call braucht überhaupt keinen Schlüssel.

403 verification_required: nur wenn Sie eine Adresse angegeben haben

Wenn Sie eine Adresse angeben und aus Ihrem Netz kürzlich bereits ein Schlüssel ausgestellt wurde (gemeinsames Büro-NAT, Universität, VPN, Mobilfunkanbieter, oder schlicht Sie selbst beim zweiten Schlüssel), schickt die API einen 6-stelligen Code an diese Adresse und antwortet:

{
  "error": "verification_required",
  "message": "A key was already issued from this network recently, so this one needs a verified mailbox: we sent a 6-digit code to you@company.com. Repeat this request within 15 minutes as {\"email\": \"...\", \"code\": \"123456\"}."
}

Senden Sie dieselbe Anfrage erneut mit einem code-Feld, innerhalb von 15 Minuten. Die Werte von reason sind die aus der Tabelle oben, dazu too_many_attempts nach 5 falschen Codes: einmal gesperrt, lehnt die Abfrage auch den richtigen Code ab, und nur eine neue Anfrage ohne code hilft.

Senden Sie die Anfrage nicht ohne code erneut, nur um es nochmals zu versuchen: das verschickt jedes Mal einen neuen Code, und die Zahl der Codes pro Adresse und Tag ist gedeckelt. Dieser ganze Schritt entfällt, wenn Sie keine Adresse senden: der anonyme Weg verschickt nie etwas.

Die übrigen Ablehnungen

Nichts davon betrifft die beiden kostenpflichtigen Wege: Prepaid-Guthabenpakete und x402 Pay-per-Call stellen keinen kostenlosen Schlüssel aus und durchlaufen keine Bestätigung.

Ihren API-Schlüssel verwenden

Übermitteln Sie den Schlüssel im Authorization-Header als Bearer-Token:

curl -X POST https://api.ibanforge.com/v1/iban/validate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…" \
  -d '{"iban": "CH10 0023 0000 0000 1234 5"}'

X-API-Key: ifk_… funktioniert ebenfalls, falls ein Bearer-Header in Ihrem Client unpraktisch ist.

Der Schlüssel funktioniert auf allen kostenpflichtigen Endpunkten:

• POST /v1/iban/validate
• POST /v1/iban/batch
• GET /v1/bic/:code
• POST /v1/iban/compliance
• GET /v1/ch/clearing/:iid

Die Angebote im Überblick

Namensnennung auf beiden kostenlosen Stufen. Jede Antwort eines kostenpflichtigen Endpunkts, die über einen kostenlosen Schlüssel läuft — anonym oder beansprucht —, trägt ein Objekt attribution (text, url, note). Wenn Sie diese Ergebnisse Menschen zeigen (eine Seite, ein Bildschirm, ein Dokument), blenden Sie „Powered by IBANforge" mit dem Link ein; ein Ergebnis, das in Ihrem Backend bleibt, schuldet nichts. Bezahlte Tarife tragen keine Namensnennung.

Das Kontingent wird über alle Endpunkte geteilt und setzt sich auf Basis monthly am 1. jedes Monats zurück (ein gegen eine Zahlung angehobener oder während eines Alarms entstandener Schlüssel trägt basis: lifetime und setzt sich nicht zurück). Batch-Validierung zählt 1 Anfrage pro IBAN — ein Batch mit 50 IBANs verbraucht 50 Anfragen (oder 50 Prepaid-Credits), dieselbe Regel wie der x402-Preis pro IBAN.

Ihre Nutzung prüfen

curl https://api.ibanforge.com/v1/keys/usage \
  -H "Authorization: Bearer ifk_3f9c1a7e2b5d40c8…"

Antwort (200 OK)

{
  "used": 7,
  "limit": 25,
  "remaining": 18,
  "month": "2026-09",
  "key_prefix": "ifk_3f9c1a7e",
  "basis": "monthly",
  "tier": "anonymous",
  "claim": {
    "url": "https://api.ibanforge.com/v1/keys/claim",
    "raises_limit_to": 200,
    "methods": ["email_code", "x402", "credits"],
    "paid_so_far_usd": 0,
    "paid_needed_usd": 1
  }
}

limit ist 25 bei einem anonymen und 200 bei einem beanspruchten Schlüssel; tier sagt, welcher vorliegt. basis sagt, welche Obergrenze wirklich gilt: monthly ist der Normalfall mit Reset am 1., lifetime gehört zu einem per Zahlung beanspruchten Schlüssel — seine 200 zählen einmalig über alle Monate und werden nicht aufgefüllt — und credits ist ein Prepaid-Guthaben, gegen das limit nichts durchsetzt. Der claim-Block wird nur bei einem noch beanspruchbaren Schlüssel mitgeliefert.

month ist der Kalendermonat, zu dem die Zähler gehören (YYYY-MM); beim Test ohne Schlüssel zählen die Zähler pro Tag, und das Feld trägt day. Dieser Endpunkt ist kostenlos und verbraucht kein Kontingent.

Ihr Kontingent im Blick behalten

Jede authentifizierte Antwort trägt Ihre Zähler mit, bei Erfolg wie bei Ablehnung, damit Sie handeln können bevor Sie an die Grenze stossen und nicht erst dann:

X-Quota-Used: 7
X-Quota-Limit: 25
X-Quota-Remaining: 18
X-Quota-Month: 2026-09

Die Zahlen sind der Stand nach Abschluss der Anfrage: ein mit 4xx abgelehnter Aufruf wird erstattet, und diese Header berücksichtigen die Erstattung bereits. Wer lieber abfragt als Header liest: GET /v1/keys/usage liefert dieselben Zahlen, kostenlos.

Wenn Ihr Kontingent erschöpft ist

Ihre Integration landet nicht in einer Sackgasse. Sind die Anfragen des Monats aufgebraucht, antwortet die API mit 402 Payment Required (x402) statt einem harten 429 — mit Hinweis-Headern, die genau sagen, was passiert ist:

X-Quota-Exhausted: true
X-Quota-Used: 25
X-Quota-Limit: 25
X-Quota-Month: 2026-09

Der 402-Body listet Ihre Optionen maschinenlesbar auf:

1. Den Schlüssel beanspruchen — ist er noch anonym, hebt ihn ein zugesandter Code an, und das kostet nichts.
2. Prepaid-Guthabenpaket kaufen — per Karte auf der Preisseite oder in USDC via POST /v1/credits/buy/1k|5k|25k. Guthaben verfällt nie und wird an Ihren bestehenden Schlüssel gebunden.
3. Pay-per-Call via x402 — ein x402-kompatibler Client zahlt automatisch in USDC, ohne Schlüsselwechsel. Siehe x402-Zahlungen.
4. Auf den monatlichen Reset warten — auf Basis monthly setzt sich das Kontingent am 1. zurück; ein gegen eine Zahlung angehobener oder während eines Alarms entstandener Schlüssel trägt basis: lifetime und tut es nicht.

TypeScript-Beispiel

const API_KEY = process.env.IBANFORGE_API_KEY;
 
const response = await fetch("https://api.ibanforge.com/v1/iban/validate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({ iban: "CH10 0023 0000 0000 1234 5" }),
});
 
const data = await response.json();
console.log(data);

Python-Beispiel

import os
import requests
 
API_KEY = os.environ["IBANFORGE_API_KEY"]
 
response = requests.post(
    "https://api.ibanforge.com/v1/iban/validate",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={"iban": "CH10 0023 0000 0000 1234 5"},
)
 
data = response.json()
print(data)

Nächste Schritte

• Erste Schritte — der ganze Weg in zehn Minuten, vom Aufruf ohne Schlüssel bis zum Stapel von 100
• x402-Mikrozahlungen — unbegrenztes Pay-per-Call mit USDC
• IBAN-Validierung — vollständige Endpunktreferenz
• Fehlerreferenz — alle Fehlercodes und Fehlerbehebung