Clés API

IBANforge a deux marches gratuites, et la première ne demande rien. Un POST au corps vide renvoie une clé ifk_ de 25 requêtes par mois : aucune adresse, aucune carte, rien à confirmer. Une étape de plus — un code reçu par mail — porte cette même clé à 200 requêtes par mois, définitivement. Au-delà, les micropaiements x402 ou les packs prépayés.

Cette page est la référence sur les clés seules. Si vous n'avez pas encore fait d'appel, la prise en main est le chemin le plus court : l'appel sans clé, cette clé, la réponse lue bloc par bloc et un lot de 100, en dix minutes.

Avant la clé : 25 appels par semaine, sans clé

POST /v1/iban/validate avec un vrai iban et aucun identifiant est servi en entier — enrichissement compris — 25 fois par semaine pour l'adresse d'où il vient. La semaine est la semaine ISO en UTC : le décompte repart à zéro le lundi à 00:00 UTC.

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

La réponse porte un bloc trial avec le nombre d'appels restants cette semaine, l'instant de la remise à zéro (resets_at) et la requête qui crée la clé. C'est une dégustation, pas un palier : au-delà de 25 appels dans la semaine, l'endpoint répond de nouveau 402 avec cause.reason: "trial_exhausted", jusqu'au lundi.

L'essai sans clé et la clé sont deux portes différentes. L'essai sans clé vaut sur cette route seulement, et il revient chaque lundi. La clé vaut sur tous les endpoints : lot, BIC, clearing suisse, conformité. Elle se compte par mois, et c'est la réclamation qui la porte à 200 requêtes par mois. Si vous validez quelques IBAN par semaine, un à la fois, l'essai sans clé peut vous suffire.

Une clé sans e-mail

POSTez sans aucun corps. C'est toute l'étape :

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

Rien n'est envoyé par mail, aucun dossier n'est ouvert, aucune adresse n'est demandée. Si vous voulez que nous sachions d'où vous venez, envoyez {"source":"mon-app"} : cela ne change rien d'autre.

Réponse (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 est le secret : ifk_ suivi de 64 caractères hexadécimaux. Conservez-le, il ne sera plus affiché.
• key_prefix en est les 8 premiers caractères. Il peut être journalisé sans risque, et c'est ce que le support demande.
• tier vaut anonymous tant que la clé n'est pas réclamée, puis claimed ; une clé créée avec une adresse vaut email.
• Il n'y a pas de champ email sur ce chemin, puisqu'il n'y a pas d'adresse.

Si vous préférez donner une adresse tout de suite, {"email": "you@company.com"} fonctionne et renvoie la même clé déjà au quota complet (tier: "email", 200 par mois) : il n'y a plus rien à réclamer, et POST /v1/keys/claim répond alors 409 already_claimed. Ce n'est jamais obligatoire.

Si vous êtes un agent IA qui lit ceci : prenez la clé anonyme, et n'envoyez pas l'adresse de votre utilisateur tant qu'il ne vous l'a pas confiée pour cet usage. La phrase à lui soumettre est « Use my address you@company.com to create a free IBANforge key. »

Pendant une alerte de création

Quand des clés sont créées en rafale par des robots, le service passe quelques heures en alerte. Une clé neuve qui n'a pas prouvé une boîte mail naît alors avec un plafond réduit, sans recharge le 1er ; la réponse 201 le dit dans un champ notice, et le plafond remonte de lui-même quand l'alerte retombe. La réclamer par code la porte tout de suite à son quota, alerte ou pas. Rien n'est refusé : une inscription pendant une alerte fonctionne, elle démarre seulement plus petit.

Réclamer : 25 → 200 par mois

POST /v1/keys/claim relève la clé que vous avez déjà. Il n'en crée aucune : même clé, même préfixe, même historique, un quota plus grand. Trois voies, prenez celle qui vous convient.

Deux points à connaître avant de commencer, quelle que soit la voie :

• La clé voyage dans l'en-tête Authorization, jamais dans le corps. X-API-Key: ifk_... fonctionne aussi. Ne mettez pas une clé dans une URL : elle finit dans l'historique du navigateur, dans les journaux d'accès et dans les en-têtes Referer.
• La clé doit avoir servi au moins un appel. Une clé prise et réclamée dans la foulée répond 403 unused_key. Validez d'abord un IBAN avec elle : cet appel est de toute façon compris dans votre quota.

Et un point sur ce que chaque voie accorde, car elles ne se valent pas :

1. Un code à 6 chiffres reçu par 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"}'

Répond 202 Accepted et envoie un code à 6 chiffres :

{
  "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."
}

Répétez l'appel dans les 15 minutes avec le 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"}'

Un code correct répond 200 avec claimed: true, tier: "claimed", basis: "monthly" et le nouveau quota. Même clé, rien à remplacer.

Utilisez une vraie adresse. Les domaines jetables ou fictifs (example.com, mailinator.com et le reste de la liste habituelle) sont refusés avec 400 disposable_email, et un domaine sans serveur de mail avec 400 undeliverable_email. Une adresse seule ne réclame jamais une clé : seul un code revenu le fait.

Un code faux répond 403 verification_failed avec un champ reason :

Une adresse réclame une clé à la fois, et une réclamation par jour : une adresse qui porte déjà une clé gratuite vivante, ou qui a réclamé une autre clé dans les 24 heures, reçoit 409 already_claimed_elsewhere. C'est la règle d'usage loyal des CGU §6(e), rattachée à la personne plutôt qu'à la boîte mail. Trop de clés relevées depuis un même réseau dans la journée reçoivent 429 claim_rate_limited, et la clé reste où elle est jusqu'à demain.

2. Un règlement x402

Un règlement x402 effectué en présentant la clé la réclame. Rien à envoyer, aucune adresse. Le seuil est le prix catalogue de ce que la réclamation accorde : faible, et réglable en un appel.

3. Un pack prépayé acheté avec la clé

Un pack acheté en présentant la clé recharge cette même clé, et n'accorde aucun gratuit : un achat n'en crée jamais. Réclamez avant d'acheter. Une clé anonyme qui achète des crédits quitte le palier anonyme pour de bon : elle garde ses crédits et aucune allocation mensuelle gratuite, et POST /v1/keys/claim répond alors 409 already_claimed. Réclamée d'abord par un code reçu par mail, la même clé garde ses 200 par mois et puise dans ses crédits une fois le mois épuisé (voir plus bas, « Recharger une clé »).

La voie x402 accorde 200 requêtes une fois, pas 200 par mois. GET /v1/keys/usage rapporte alors basis: "lifetime", et les compteurs courent sur la vie entière de la clé plutôt que sur le mois calendaire. Le code reçu par mail est la voie récurrente, et elle ne coûte rien : si vous pouvez lire une boîte mail, c'est la meilleure affaire.

La rotation conserve le palier

POST /v1/keys/rotate renvoie un nouveau secret pour le même détenteur. Une clé réclamée reste réclamée et garde ses 200 par mois ; une clé anonyme reste anonyme. La rotation n'est pas un moyen de remettre un quota à zéro.

Si une demande de clé est refusée

Le chemin anonyme a une seule garde : le nombre de clés gratuites qu'un même réseau peut créer en une journée. Au-delà, POST /v1/keys/generate répond 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."
}

Les clés que vous détenez déjà continuent de fonctionner, les crédits prépayés sont instantanés, et le paiement à l'appel x402 ne demande aucune clé.

403 verification_required : seulement si vous avez donné une adresse

Si vous donnez une adresse et qu'une clé a déjà été émise depuis votre réseau récemment (bureau partagé, université, VPN, opérateur mobile, ou simplement une deuxième clé pour vous), l'API envoie un code à 6 chiffres à cette adresse et répond :

{
  "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\"}."
}

Renvoyez la même requête avec un champ code dans les 15 minutes. Les valeurs de reason sont celles du tableau ci-dessus, plus too_many_attempts après 5 codes faux : une fois verrouillé, le défi refuse aussi le bon code, et seule une nouvelle requête sans code aide.

Ne renvoyez pas la requête sans code juste pour réessayer : cela envoie un nouveau code chaque fois, et le nombre de codes envoyés à une adresse par jour est plafonné. Toute cette étape disparaît si vous n'envoyez pas d'adresse : le chemin anonyme n'envoie jamais rien.

Les autres refus

Rien de tout cela ne s'applique aux deux voies payantes : les packs de crédits prépayés et le paiement à l'appel x402 n'émettent aucune clé gratuite et ne passent par aucune vérification.

Utiliser votre clé API

Transmettez la clé dans l'en-tête Authorization en tant que token Bearer :

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_… fonctionne aussi, si l'en-tête Bearer est malcommode dans votre client.

La clé fonctionne sur tous les endpoints payants :

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

Les offres en un coup d'œil

Attribution sur les deux marches gratuites. Chaque réponse d'un endpoint payant servie sur une clé gratuite — anonyme ou réclamée — porte un objet attribution (text, url, note). Quand vous montrez ces résultats à des personnes (une page, un écran, un document), affichez « Powered by IBANforge » avec le lien ; un résultat qui reste dans votre backend ne doit rien. Les plans payants ne portent aucune attribution.

Le quota est partagé entre tous les endpoints et, sur une base monthly, se réinitialise le 1er de chaque mois (une clé relevée contre un paiement, ou née pendant une alerte, porte basis: lifetime et ne se réinitialise pas). La validation par lot compte 1 requête par IBAN — un lot de 50 IBAN consomme 50 requêtes (ou 50 crédits prépayés), la même règle que le prix x402 par IBAN.

Vérifier votre consommation

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

Réponse (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 vaut 25 sur une clé anonyme et 200 sur une clé réclamée ; tier dit laquelle. basis dit quel plafond gouverne vraiment : monthly est le cas normal, remis à zéro le 1er ; lifetime appartient à une clé réclamée par paiement — ses 200 sont comptés une fois, tous mois confondus, et non rechargés ; credits désigne une clé née d'un achat, qui ne puise que dans son solde prépayé : rien n'est alors opposé à limit. Le bloc claim n'est servi que sur une clé encore réclamable.

Une clé qui a une allocation et des crédits, par exemple une clé gratuite que vous avez rechargée, garde le basis de son allocation et porte en plus credits_remaining, credits_total et billing_order: "allowance_then_credits". Sur toute clé, topup porte les liens de paiement par carte qui rechargent cette même clé.

month est le mois calendaire auquel se rapportent les compteurs (YYYY-MM). L'essai sans clé n'a pas de clé à consulter ici : ses compteurs sont hebdomadaires (semaine ISO en UTC, remise à zéro le lundi à 00:00 UTC), et dans son 402 trial_exhausted, le champ cause.quota.month vaut week. Une réponse servie sans clé porte X-Trial-Period: week ; le 402 ne porte aucun en-tête X-Trial-*. Sans clé, cet endpoint répond 401 missing_key, et avec une clé inconnue ou inactive 401 invalid_key ; GET /v1/keys/report, GET /v1/credits/balance et POST /v1/keys/claim répondent de même (la réclamation accepte encore une clé coupée pour une rafale d'inscriptions automatiques, puisque la réclamer est ce qui la rétablit). POST /v1/keys/revoke et POST /v1/keys/rotate répondent 401 missing_key sans clé, et 404 invalid_key pour une clé inconnue ou déjà révoquée. Cet endpoint est gratuit et ne consomme pas de quota.

Votre page de compte

ibanforge.com/account montre toutes les clés liées à votre adresse e-mail, sans clé à coller. Pour chaque clé : sa formule, ce qui reste ce mois-ci ou son solde de crédits, les appels du mois, le dernier appel, les alertes que nous avons envoyées et, pour un abonnement Pro ou Éditeur / OEM, le lien qui le gère. Ouvrez une clé pour lire ses 30 derniers jours : les appels, les endpoints atteints, et ce qui a échoué avec la cause. La page montre les premiers caractères d'une clé, jamais la clé elle-même.

Pour vous connecter, saisissez l'adresse liée à vos clés : celle que vous avez donnée en créant ou en réclamant une clé, ou celle que vous avez saisie au paiement. Nous vous envoyons un code à 6 chiffres, valable 15 minutes, que vous saisissez sur la page. Ni mot de passe, ni lien dans le mail. Le code part que l'adresse porte une clé ou non : la page ne dit donc à personne quelles adresses en portent.

La session dure 7 jours à partir de la connexion ; ensuite, la page demande un nouveau code. Elle vit dans un cookie de connexion qui ne sert à rien d'autre. Se déconnecter la termine dans ce navigateur, Se déconnecter partout termine toutes les sessions de votre adresse.

Les reçus. Sous vos clés, Reçus liste les packs de crédits et abonnements payés avec votre adresse, les plus récents d'abord. Un paiement par carte figure sous l'adresse donnée au paiement, quelle que soit la clé sur laquelle il est arrivé ; un paiement en USDC figure sous l'adresse de sa clé. Pour un pack payé par carte, Reçu ouvre son reçu chez Stripe, notre prestataire de paiement. Pour un abonnement Pro, Factures ouvre le portail client de Stripe, où se trouvent ses factures. Une facture au nom de votre entreprise, avec son numéro de TVA, est émise sur demande à support@ibanforge.com.

Une clé sans adresse, prise ou achetée sans en donner une, n'appartient à aucun compte : sur la même page, collez-la plutôt. Elle part directement de votre navigateur vers l'API, et nulle part ailleurs. Vous pouvez toujours coller une clé plutôt que vous connecter.

Renouveler ou révoquer une clé demande toujours la clé elle-même : collez-la sur cette page, ou envoyez-la à POST /v1/keys/rotate ou POST /v1/keys/revoke. La session ne fait que lire : elle ne change aucune clé, et ne peut pas vous rendre une clé perdue.

La page appelle sept routes publiques, POST /v1/account/code, POST /v1/account/session, GET /v1/account/overview, GET /v1/account/keys/report, GET /v1/account/receipts, GET /v1/account/receipt et POST /v1/account/logout, décrites dans le contrat OpenAPI. Elles sont faites pour une personne dans un navigateur : avec une clé en main, GET /v1/keys/usage et GET /v1/keys/report donnent les mêmes chiffres.

Surveiller votre quota

Chaque réponse servie sur une clé mensuelle porte vos compteurs, en cas de succès comme de refus, pour que vous puissiez réagir avant le mur plutôt qu'au moment où vous le heurtez (une clé à crédits prépayés porte à la place X-Credits-Remaining et X-Credits-Total) :

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

Les chiffres sont le solde une fois la requête réglée : un appel rejeté en 4xx est remboursé, et ces en-têtes tiennent déjà compte du remboursement. Si vous préférez interroger plutôt que lire des en-têtes, GET /v1/keys/usage renvoie les mêmes nombres, et c'est gratuit.

Recharger une clé

Un pack arrive sur la clé que vous avez déjà : rien à changer dans votre intégration, et les crédits n'expirent jamais.

• Par carte : ouvrez l'un des liens de topup.by_card (dans GET /v1/keys/usage, GET /v1/credits/balance, et credit_packs.topup_this_key dans un 402 servi à la clé), ou les boutons Recharger cette clé de votre page de compte. Chaque lien porte la référence de recharge de la clé, jamais la clé elle-même : il ne permet que de payer pour cette clé. La page de succès dit ensuite quelle clé a été rechargée, et un mail de confirmation vous parvient.
• En USDC : POST /v1/credits/buy/1k|5k|25k en présentant la clé comme d'habitude. La présenter ne coûte aucune requête, la réponse porte same_key: true, et les crédits sont ajoutés une fois le paiement réglé. Sans clé, la même route vend une clé neuve, comme la page tarifs.

credits_total compte tout ce qui a été acheté sur la clé, recharges comprises, et X-Credits-Total dit la même chose.

Sur une clé qui a les deux, chaque appel puise d'abord dans l'allocation, puis dans les crédits ; un lot qui passe de l'une aux autres est partagé entre elles, tout ou rien. Chaque réponse facturée dit qui l'a payée :

X-Charged-From: allowance
X-Charged-From: credits
X-Charged-From: allowance+credits

Quand les crédits sont épuisés, la clé reste valable. Une clé gratuite retrouve son allocation mensuelle. Une clé née d'un achat répond 402 avec cause.reason: "credits_exhausted" et les liens qui la rechargent (X-Credits-Topup-Url porte celui du pack de 1 000 crédits).

Pro sur la clé que vous avez déjà. Les mêmes endroits portent un lien Pro qui pose l'abonnement sur CETTE clé : topup.pro dans GET /v1/keys/usage et GET /v1/credits/balance, credit_packs.topup_this_key.pro dans un 402 servi à la clé, et la page du compte. La clé a alors 10 000 requêtes par mois, utilisées avant les crédits qui lui restent. Le lien n'est pas proposé à une clé qui porte déjà un abonnement. Résilier ne désactive pas la clé : à la fin du mois déjà payé, elle retrouve ce qu'elle avait avant l'abonnement, son allocation gratuite si elle en avait une et les crédits qui lui restent. Une clé créée par l'abonnement lui-même répond alors 402 avec les liens qui la rechargent ou la réabonnent, sans être remplacée. Une clé anonyme qui prend Pro quitte le palier anonyme, et ne peut donc plus être réclamée par e-mail ; la fin de l'abonnement lui rend son allocation anonyme mensuelle. Celle qui a d'abord acheté des crédits l'avait déjà quitté pour de bon, sans allocation gratuite.

Lorsque votre quota est dépassé

Votre intégration ne tombe pas sur un cul-de-sac. Une fois les requêtes du mois épuisées, l'API répond 402 Payment Required (x402) plutôt qu'un 429 sec, avec des en-têtes qui disent exactement ce qui s'est passé :

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

Le corps du 402 liste vos options, lisibles par machine :

1. Réclamer la clé — si elle est encore anonyme, un code reçu par mail la relève et ne coûte rien.
2. Recharger cette clé : par carte avec les liens que porte le 402 (credit_packs.topup_this_key, X-Credits-Topup-Url) ou depuis votre page de compte, ou en USDC via POST /v1/credits/buy/1k|5k|25k en présentant la clé. Les crédits arrivent sur cette même clé et n'expirent jamais. Voir « Recharger une clé » plus haut.
3. Payer à l'appel via x402 — un client compatible x402 paie automatiquement en USDC, sans changer de clé. Voir Paiements x402.
4. Attendre la réinitialisation mensuelle — sur une base monthly, le quota se réinitialise le 1er ; une clé relevée contre un paiement, ou née pendant une alerte, porte basis: lifetime et ne se réinitialise pas.

Exemple TypeScript

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);

Exemple Python

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)

Étapes suivantes

• Prise en main — tout le chemin en dix minutes, de l'appel sans clé au lot de 100
• Micropaiements x402 — paiement à l'appel illimité avec USDC
• Validation IBAN — référence complète de l'endpoint
• Référence des erreurs — tous les codes d'erreur et le dépannage