Raccourcis clavier

Appuyez sur ← ou → pour passer d'un chapitre à l'autre

Appuyez sur S ou / pour rechercher dans la documentation

Appuyez sur ? pour afficher cette aide

Appuyez sur Échap pour masquer cette aide

Documentation Swagger : contrat OpenAPI et authentification

forge-api sert son contrat OpenAPI lui-même, généré depuis le code avec la bibliothèque utoipa. Il n'existe pas d'interface Swagger UI servie par le backend : vous récupérez le document et l'ouvrez dans l'outil de votre choix (Swagger Editor, Postman, Insomnia, générateur de client).

Dans les exemples de ce livre, <hote-api> désigne le nom d'hôte de l'API, sans schéma : app.<domaine> derrière le nom public (voir Diagnostics et signalement). Sur un poste de développement, écrivez http://localhost:3000 à la place de https://<hote-api>.

Où récupérer le contrat

RouteContenu
GET /api/v1/openapi.jsonDocument OpenAPI en JSON
GET /api/v1/openapi.yamlLe même document en YAML
GET /openapi.jsonMême source, à la racine du serveur
GET /openapi.yamlMême source, à la racine du serveur

Ces routes sont publiques. La variable OPENAPI_ENABLED=false les coupe : elles répondent alors 404. Le champ servers du document vaut / parce que les chemins documentés portent déjà le préfixe /api/v1.

curl "https://<hote-api>/api/v1/openapi.json" -o forge-openapi.json

Ce que couvre le contrat, et ce qu'il ne couvre pas

Le contrat est partiel. Il se limite aux opérations annotées avec #[utoipa::path] dans crates/forge-api/src/openapi/. Mesures reproductibles :

FaitCommandeRésultat
Opérations annotéesgit grep -hoE '#\[utoipa::path\(' -- crates/forge-api/src/openapi | wc -l125
Chemins distinctsgit grep -hoE 'path = "/api/v1[^"]*"' -- crates/forge-api/src/openapi | sort -u | wc -l109
Appels .route( actifs dans router.rsgit grep -c '^\s*\.route(' -- crates/forge-api/src/router.rs793

Familles documentées (étiquettes du contrat) : santé, facturation, authentification, OAuth/OIDC, SSO, sessions, chat, passerelle de chat, messages de gateway, prédictions, documents (RAG, document store, scraping, chunks), clés d'API, compte, rôles.

Familles absentes du contrat : le transport MCP (/api/v1/mcp), le catalogue métier (/api/v1/mcp/catalog-business/*), la gestion des gateways (/api/v1/gateways/*), les retours (/api/v1/feedback), les outils, variables et identifiants. Pour ces routes, la référence est ce livre, qui les décrit une par une d'après le routeur.

Le document déclare trois schémas de sécurité : BearerAuth (JWT dans Authorization: Bearer), CookieAuth (cookie jwt) et ApiKeyAuth (en-tête X-API-Key). Seuls les deux premiers sont consommés par des routes aujourd'hui : ApiKeyAuth est déclaré sans route qui l'accepte.

Authentification

La majorité des routes exigent un jeton, donc un compte (Prise en main guidée, étape 1). Il s'obtient par la connexion, avec un second facteur (OTP e-mail ou application TOTP) lorsqu'il est exigé :

# 1. connexion
curl -X POST "https://<hote-api>/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"<email>","password":"<mot-de-passe>"}'

La réponse porte requires_2fa. Quand il vaut false et que la connexion réussit, elle contient directement token : passez à l'envoi du jeton plus bas. Un e-mail inconnu ou un mot de passe erroné répond 401 (UNAUTHORIZED), et si requires_mfa_enrollment vaut true, aucun jeton n'est rendu : enrôlez d'abord un second facteur. Quand requires_2fa vaut true, la réponse contient aussi two_factor_token et method (email ou totp) :

# 2. validation du second facteur
curl -X POST "https://<hote-api>/api/v1/auth/2fa/verify" \
  -H "Content-Type: application/json" \
  -d '{"two_factor_token":"<two_factor_token>","code":"<code>"}'

La réponse est {"authenticated": true, "token": "<token>"}. Le renvoi du code par e-mail se fait par POST /api/v1/auth/2fa/resend. La connexion par fournisseur d'identité (OIDC) passe par GET /api/v1/auth/oidc/login.

Ensuite, joignez le jeton à chaque appel (les tutoriels le rangent dans la variable JWT) :

Authorization: Bearer <token>

Les navigateurs utilisent le cookie jwt posé par la connexion. Le jeton vit 7 jours par défaut (variable JWT_EXPIRY). POST /api/v1/auth/refresh (alias POST /api/v1/auth/refreshToken) renouvelle une session encore valide et rend {"token": ...} ; il n'existe pas de jeton de rafraîchissement séparé : un jeton expiré ne peut pas être renouvelé, il faut se reconnecter.

Quelques routes sont publiques (santé, contrat OpenAPI, conformité publique, prediction/{id} d'une gateway publiée, SBOM).

Provisionnement SCIM

Le provisionnement d'utilisateurs et de groupes suit SCIM 2.0 sous /api/v1/scim/v2/ : Users, Groups, ServiceProviderConfig, Schemas et ResourceTypes. Il s'authentifie par un jeton porteur SCIM dédié.

Format des erreurs

Une erreur est un objet {"error": {"code": "...", "message": "..."}} ; les erreurs de l'extracteur d'authentification ajoutent status. Codes fréquents : UNAUTHORIZED (401), FORBIDDEN (403), NOT_FOUND (404), VALIDATION_FAILED (422), FEATURE_PENDING (503, capacité prévue non livrée). Le dépassement de débit est différent : le limiteur répond 429 avec un corps vide et l'en-tête retry-after (en secondes). Le transport MCP répond, lui, en erreurs JSON-RPC (error.code, error.message) : voir Routes MCP.

Limites de débit

Le limiteur est par adresse IP et par préfixe de route (le préfixe de longueur maximale l'emporte) :

PréfixeDéfautRéglage
/api/v1/100 requêtes par secondeFORGE_RATE_LIMIT_PER_SEC
/api/v1/prediction (début de chemin : couvre aussi /api/v1/predictions)20 requêtes par minuteFORGE_RATE_LIMIT_PREDICTION_PER_MIN
/api/v1/stats/route-events30 requêtes par minutefixe

Les routes d'authentification ont en plus leurs propres limiteurs (auth_rate_limiter, account_rate_limiter).

Voir aussi