ZodBack Docs
CtrlK
v2.4

CORS et origines autorisees

Fonctionnement du CORS ZodBack : paths publics auto-autorises, origines statiques vs dynamiques, erreurs courantes.

CORS et origines autorisees

Le CORS (Cross-Origin Resource Sharing) est le mecanisme qui autorise ou bloque les appels API depuis un navigateur. ZodBack gere le CORS a deux niveaux.

Niveau 1 : Middleware CORS (main.ts)

Le middleware NestJS CORS definit quelles origines peuvent appeler le backend.

Origines statiques (toujours autorisees)

Ces origines sont toujours acceptees, quel que soit le path :

  • FRONTEND_URL (ex: https://app.zoddev.site)
  • PORTFOLIO_ORIGIN (si defini dans .env)
  • 127.0.0.1:3014 (dev local)

Origines dynamiques (paths publics)

Pour les paths publics, toute origine est acceptee par le middleware CORS :

Path pattern Module
/api/blog/v1/public/* Blog
/api/portfolio/v1/public/* Portfolio
/api/docs/v1/public/* Documentation

Le middleware laisse passer la requete, mais la vraie validation se fait au niveau du guard.

Niveau 2 : ApiTokenGuard

Le guard valide le token et verifie les allowedOrigins configurees dans le token :

  1. Si le token a des allowedOrigins definies et que le header Origin ne correspond pas → 403 Forbidden
  2. Si le token n'a pas d'allowedOrigins → toute origine est acceptee (utile pour les tokens de test)

Ce que vous n'avez PAS besoin de modifier

Pour un site externe standard utilisant les endpoints publics existants (blog, portfolio, docs) :

  • Pas de modification du backend — le CORS dynamique accepte deja toute origine sur les paths publics
  • Pas de variable d'environnement a ajouter — sauf si vous voulez ajouter une origine statique

Ce que vous DEVEZ configurer

  1. Dans le token : renseignez les Allowed Origins (ex: https://mon-blog.zoddev.site) pour securiser l'acces
  2. Dans votre site : assurez-vous que les requetes partent bien du domaine declare

Erreurs CORS courantes

Erreur Cause Solution
CORS: origin header required in production Requete sans header Origin (ex: curl sans -H Origin) Ajoutez -H "Origin: https://votre-domaine.com"
Access-Control-Allow-Origin missing Le path n'est pas un path public reconnu Verifiez le prefix du path (/api/.../v1/public/...)
403 Forbidden L'origine n'est pas dans les allowedOrigins du token Mettez a jour les origines autorisees du token dans le dashboard
CORS preflight failed Le serveur ne repond pas au OPTIONS Verifiez que le backend est accessible et que le path existe

Test CORS avec curl

# Simuler une requete navigateur avec Origin
curl -s "https://api.zoddev.site/api/blog/v1/public/posts" \
  -H "x-api-key: <TOKEN>" \
  -H "X-Project-Id: 1" \
  -H "Origin: https://mon-blog.zoddev.site" \
  -v 2>&1 | grep -i "access-control"

Si vous voyez Access-Control-Allow-Origin: https://mon-blog.zoddev.site, le CORS est correctement configure.