DocumentationAPI proxyShield anti-bot

Keywall API Platform

Une documentation pratique pour brancher Keywall proprement: garder les secrets cote serveur, exposer des routes proxy controlees, limiter les abus et verifier Shield sur les actions sensibles.

Secrets invisibles

Le frontend ne transporte jamais la vraie cle provider.

Limites configurables

Rate limits, budgets et taille de payload sont controles avant l'upstream.

Logs exploitables

Chaque appel garde un request_id pour debugger vite sans fuite de secret.

Quickstart

Faire le premier appel en quelques minutes

Le chemin minimal consiste a creer un projet, ajouter le secret provider, definir une route proxy puis appeler cette route avec une cle publique.

Creer un projet

Un projet regroupe une application, ses environnements, ses routes proxy, ses budgets et ses logs.

Ajouter un secret

La vraie cle OpenAI, Mistral, Stripe ou autre provider reste chiffree cote serveur.

Publier une route

Expose un endpoint stable comme /ai/chat ou /billing/customer avec les methodes autorisees.

Utiliser la cle publique

Le navigateur envoie seulement une cle pk_ et Keywall injecte le secret au dernier moment.

Premier appel

bash

curl https://keywall.eu/api/proxy/project_xxx/ai/chat \
  -H "x-keywall-key: pk_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "input": "Resume ce message en une phrase."
  }'

Concepts

Les objets a connaitre

Keywall reste simple si chaque element a une responsabilite claire. Le frontend identifie la route, Keywall valide, puis le provider recoit uniquement une requete deja controlee.

Projet

Conteneur logique pour une app ou un client. Il isole les routes, les cles et les limites.

Cle publique

Identifiant frontend utilisable dans le navigateur. Elle ne donne jamais acces au secret provider.

Secret provider

Cle privee stockee dans le coffre-fort Keywall puis ajoutee cote serveur sur l'appel upstream.

Route proxy

Contrat entre ton frontend et une API externe: URL, methode, headers, payload et limites.

Shield

Checkpoint anti-bot qui produit un token court a verifier sur les actions sensibles.

Budget

Limite de cout, volume ou frequence pour couper les abus avant qu'ils touchent le provider.

Environnements

Separer test, preview et production

Utilise des cles publiques differentes pour eviter qu'un build local ou une preview consomme les budgets de production.

Local

http://localhost:3000

Budget bas, logs verbeux, secrets de test.

Preview

https://preview.example.com

Origines ephemeres, limites strictes, donnees non critiques.

Production

https://app.example.com

Secrets live, alertes budget et Shield active.

Routes proxy

Definir un contrat strict avec l'API externe

Une route proxy doit etre precise. Plus elle est contrainte, moins un utilisateur peut transformer ton frontend en client libre vers le provider.

route.config.json

json

{
  "slug": "ai/chat",
  "upstream": "https://api.openai.com/v1/responses",
  "method": "POST",
  "secret": "OPENAI_API_KEY",
  "allowedOrigins": ["https://app.example.com"],
  "limits": {
    "requestsPerMinute": 60,
    "maxBodyKb": 32,
    "monthlyBudgetEur": 50
  },
  "forceBody": {
    "model": "gpt-5-mini"
  }
}

Anatomie d'une route

Origines

Liste les domaines autorises: production, preview et local si necessaire.

Methodes

Autorise uniquement GET, POST, PATCH ou DELETE quand la route en a besoin.

Headers

Supprime les headers dangereux et force ceux qui doivent rester constants.

Payload

Bloque les champs interdits, impose les valeurs critiques et limite la taille.

Budget

Fixe un plafond par minute, jour ou mois selon le cout de l'API externe.

Logs

Garde le request_id, le statut et le cout estime sans enregistrer de secret.

Requete frontend

Appeler Keywall depuis l'application

L'appel ressemble a un fetch classique. La difference importante: la cle envoyee est publique, limitee et liee a une route.

app/api.ts

typescript

const response = await fetch("https://keywall.eu/api/proxy/project_xxx/ai/chat", {
  method: "POST",
  headers: {
    "x-keywall-key": "pk_live_xxxxxxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-5-mini",
    input: message
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.code ?? "keywall_error");
}

const result = await response.json();

Securite

Ce que Keywall verifie avant l'upstream

Chaque requete passe par une serie de controles rapides. Une requete bloquee par Keywall n'est pas facturee par le provider externe.

Cle publique

Presence, format, environnement actif et projet associe.

Origin

Comparaison avec les domaines autorises pour l'environnement.

Route

Slug, methode, secret rattache, upstream et statut de publication.

Payload

Taille, champs interdits, valeurs forcees et schema attendu.

Budget

Volume, frequence, plafond mensuel et cout estime de la route.

Upstream

Timeout, erreurs provider et reponse normalisee pour le frontend.

Erreurs

Codes previsibles pour debugger vite

Les erreurs Keywall doivent etre traitees comme une reference stable cote frontend. Affiche un message utilisateur simple et garde le request_id pour les logs.

Code	HTTP	Cause
invalid_api_key	401	La cle publique est absente, invalide ou rattachee a un environnement inactif.
origin_not_allowed	403	Le domaine appelant n'est pas dans la liste des origines autorisees.
route_not_found	404	Le slug de route ne correspond a aucune route active du projet.
method_not_allowed	405	La methode HTTP n'est pas autorisee pour cette route.
rate_limit_exceeded	429	La limite de frequence est atteinte avant l'appel au provider.
budget_exceeded	402	Le budget configure bloque la requete pour eviter une facture abusive.
payload_too_large	413	Le corps de requete depasse la taille maximale configuree.
security_rule_blocked	403	Une regle de route a bloque le payload, le modele, le header ou la cible.
upstream_timeout	504	Le provider externe n'a pas repondu dans le delai autorise.
upstream_error	502	Le provider externe a renvoye une erreur non resolue par Keywall.

Keywall Shield

Installer le checkpoint anti-bot

Shield ajoute un signal client leger pour proteger formulaires, inscriptions, endpoints couteux et actions sujettes au spam.

npm

typescript

npm install keywall-shield

import { KeywallShield } from "keywall-shield";

const shield = new KeywallShield({
  siteKey: "shield_live_xxxxxxxxx",
  baseUrl: "https://keywall.eu",
  autoFetch: true
});

shield.protectForms();

script fallback

html

<script
  src="https://keywall.eu/api/shield/widget.js"
  data-keywall-site-key="shield_live_xxxxxxxxx">
</script>

Verification serveur

Ne jamais faire confiance au token cote client

Le token Shield doit etre envoye a ton backend ou a une route serveur, puis verifie avec Keywall avant d'executer l'action sensible.

server.ts

typescript

const response = await fetch("https://keywall.eu/api/shield/siteverify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    siteKey: "shield_live_xxxxxxxxx",
    token:
      request.headers.get("x-keywall-shield-token") ??
      request.cookies.get("kw_shield_token")?.value ??
      formData.get("keywall_shield_token")
  })
});

const result = await response.json();

if (!result.success || result.score < 50) {
  return new Response("Blocked", { status: 403 });
}

Bonnes pratiques

Garder la surface d'attaque courte

La bonne configuration Keywall est restrictive par defaut. Tu ouvres ensuite uniquement ce dont le produit a vraiment besoin.

Une route par usage

Evite les routes generiques qui laissent le frontend choisir librement l'upstream.

Modeles forces

Pour les APIs IA, force le modele et les parametres couteux cote route.

Budgets bas au debut

Commence strict, observe les logs, puis augmente les limites avec des donnees reelles.

Messages courts

Ne renvoie pas les details provider bruts aux utilisateurs finaux.

Rotation des secrets

Remplace les secrets apres incident, changement d'equipe ou migration provider.

Request ID partout

Propager l'identifiant facilite le support sans exposer de contenu sensible.

SDK

Interface cible pour les apps JavaScript

Le SDK garde une API compacte tout en conservant les memes garanties que l'appel HTTP direct.

sdk.ts

typescript

import { Keywall } from "@keywall/sdk";

const keywall = new Keywall({
  publicKey: "pk_live_xxxxxxxxx"
});

const result = await keywall.proxy.call("ai/chat", {
  input: "Hello",
  model: "gpt-5-mini"
});

Production

Checklist avant mise en ligne

Cette liste couvre les erreurs qui exposent le plus vite une cle, un budget ou une action sensible.

Les secrets test et live sont separes.

Les domaines de preview et production sont explicitement autorises.

Chaque route a une limite de taille, de frequence et de budget.

Les logs ne contiennent ni Authorization, ni cookie, ni payload sensible.

Shield est verifie cote serveur sur les formulaires et actions couteuses.

Les erreurs frontend affichent un message court et conservent le request_id.