Authentification
Chaque requête authentifiée porte une clé d'API bearer. La clé identifie l'établissement sur lequel vous agissez et les portées que vous avez le droit d'utiliser. Il n'y a ni identifiants, ni mots de passe, ni parcours OAuth : une clé par intégration.
Une clé d'API Veridien ressemble à ceci :
vrdn_live_xxxxxxxxxxxxxxxxxxxx- Elle est préfixée par
vrdn_live_. - Elle n'est affichée qu'une seule fois, à sa création. Veridien ne conserve qu'un hachage SHA-256 de la clé ; elle ne peut jamais être récupérée, seulement révoquée et remplacée.
- Elle est liée à un seul établissement. L'établissement est déduit de la clé, aucun endpoint ne vous demande donc d'identifiant d'établissement.
Traitez les clés comme des mots de passe
Une clé donne ses portées sur les données réelles de votre établissement. Gardez-la dans un coffre à secrets côté serveur ou dans une variable d'environnement, jamais dans du code côté client ni dans un dépôt public. Si une clé fuite, révoquez-la immédiatement et émettez-en une nouvelle.
Créez les clés dans le tableau de bord, sous Paramètres → Clés d'API :
- Cliquez sur Créer une clé et donnez-lui un nom parlant (par exemple,
Sunrise Bay booking engine). - Sélectionnez les portées dont l'intégration a besoin, en n'accordant que le minimum nécessaire.
- Copiez la clé affichée dans la boîte de dialogue de confirmation et rangez-la en lieu sûr. Elle ne sera plus jamais affichée.
Les clés peuvent être révoquées à tout moment depuis le même écran. Une clé révoquée cesse de fonctionner immédiatement ; les requêtes qui l'utilisent renvoient alors 401.
Placez la clé dans l'en-tête Authorization de chaque requête :
curl https://veridien.app/api/v1/me \
-H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"Un appel réussi à /me confirme que la clé fonctionne et indique son établissement et ses portées :
{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "reservations:write", "folio:write"],
"request_id": "req_a1b2c3d4e5"
}Si l'en-tête est absent ou mal formé, vous obtenez 401 missing_api_key ; si la clé est inconnue, désactivée ou expirée, vous obtenez 401 invalid_api_key.
Une clé ne peut appeler un endpoint que si elle détient la portée de cet endpoint. Appeler un endpoint sans sa portée renvoie 403 insufficient_scope. Les portées suivent la forme resource:action.
| Portée | Donne accès à |
|---|---|
availability:read | Lire les disponibilités et les tarifs (/availability, /rates, /room-types, /services, et les offres publiées). |
rates:read | Lire les ressources de gestion tarifaire (GET /rate-plans/{id}/intervals, /inclusions, /promo-codes). Les endpoints de lecture des prix (/rates, /rate-plans) acceptent availability:read. |
rates:write | Créer, modifier et supprimer des tarifs et des promotions, des périodes saisonnières, des prestations incluses et des crédits, et des codes promo (/rate-plans, /intervals, /promo-codes). |
reservations:read | Lister et lire les réservations (/reservations, /reservations/{id}). |
reservations:write | Créer des blocages, confirmer des réservations et annuler (/holds, /holds/{id}/confirm, /reservations/{id}/cancel). |
guests:read | Lire les fiches clients, sans les données personnelles. |
guests:read:pii | Renvoyer en plus les données personnelles du client (e-mail, téléphone, adresse, document). |
guests:write | Enregistrer, rattacher et mettre à jour des clients (POST /guests, PATCH /guests/{id}). |
loyalty:read | Lire le solde de fidélité d'un client, son niveau et son historique. |
loyalty:write | Utiliser des points de fidélité (/loyalty/redemptions). |
folio:read | Lire la note d'une réservation. |
folio:write | Passer des frais sur une note (/reservations/{id}/folio/charges). |
webhooks:manage | Réservé à la gestion des abonnements aux webhooks, à venir. |
Moindre privilège
N'accordez que les portées dont une intégration a besoin. Un widget de disponibilités en lecture seule n'a besoin que d'availability:read ; un moteur de réservation complet demande en général availability:read, guests:write, reservations:write et folio:write, plus loyalty:* s'il affiche les points.
Les fiches clients se divisent en une vue de base et une vue avec données personnelles. Avec guests:read, vous recevez les identifiants et les champs non sensibles (nom, nationalité, statut, indicateur de vérification de résidence locale). Pour recevoir en plus email, phone, address et les champs de document, la clé doit aussi détenir guests:read:pii. Vous pouvez ainsi construire, par exemple, un widget public qui lit le statut d'un client sans jamais exposer ses coordonnées.
Deux endpoints méta ne demandent ni clé ni portée :
GET /health: une sonde de disponibilité qui renvoie{ "status": "ok" }.GET /openapi.json: le schéma OpenAPI 3.1 de toute l'API.
Tout le reste exige une clé valide avec la portée appropriée.
- Conventions : erreurs, idempotence, pagination et limites de débit.
- Démarrage rapide : un parcours de réservation complet, de la clé à la réservation confirmée.