Référence API

Vue d’ensemble de l’API

Une API REST servie par le moteur AYIiD (Fastify). JSON en entrée et en sortie, jetons JWT, validation stricte des schémas.

Base URL et santé

Toutes les routes sont servies à la racine du moteur. Remplacez la base par l’origine de votre déploiement. Une sonde de santé simple est disponible.

1# Base URL (exemple)
2https://api.ayiid.example
3
4# Sonde de sante
5curl https://api.ayiid.example/health
6# { "status": "ok" }

Environnements

Chaque jeton porte un environnement. Les demandes de vérification et la facturation sont isolées par environnement : SANDBOX (défaut) pour l’intégration, PRODUCTION pour le trafic réel.

Authentification

Les routes protégées attendent un JWT dans l’en-tête Authorization. Le rôle porté par le jeton (verifier, holder, admin) conditionne l’accès. Voir Authentification.

1Authorization: Bearer <accessToken>
2Content-Type: application/json

Les erreurs suivent les codes HTTP standard. Une entrée invalide renvoie 400 (validation), un jeton absent ou invalide 401, un rôle insuffisant 403. Les routes sensibles renvoient un message générique pour ne pas guider un attaquant.

Champ	Type	Description
`400`	Bad Request	Corps ou paramètres invalides (schéma Zod).
`401`	Unauthorized	Jeton manquant, invalide ou expiré.
`403`	Forbidden	Rôle insuffisant pour la route.
`404`	Not Found	Ressource introuvable.
`429`	Too Many Requests	Limitation de débit (routes d’auth notamment).