Authentification

Chaque requête porte votre clé dans l’en-tête Authorization.

curl https://localoge.com/api/v1/channel/ping \
  -H "Authorization: Bearer lok_live_a1b2c3d4e5f6a7b8c9d0e1f2.sk_9f8e7d6c5b4a39281706f5e4"

L’en-tête X-Api-Key est accepté à l’identique, sans le mot Bearer.

La forme d’une clé

lok_live_a1b2c3d4e5f6a7b8c9d0e1f2 . sk_9f8e7d6c5b4a39281706f5e4d3c2b1a0
└──────── identifiant public ────┘   └──────────── secret ─────────────┘

L’identifiant public sert à retrouver votre compte. Le secret prouve que c’est bien vous.

Le secret ne se retrouve pas

Nous ne le stockons nulle part : seule son empreinte cryptographique est conservée. Personne chez Localoge, administrateur compris, ne peut le relire. Une clé perdue ne se récupère pas, elle se remplace : nous en créons une nouvelle et révoquons l’ancienne.

Rangez-la dans votre gestionnaire de secrets dès sa réception.

Deux environnements, deux préfixes, deux adresses

Préfixe	Environnement	URL de base
lok_test_	Sandbox : copie séparée de Localoge, aucun paiement réel, aucun e-mail sortant.	https://sandbox.localoge.com/api/v1/channel
lok_live_	Production.	https://localoge.com/api/v1/channel

Chaque clé ne fonctionne que sur son instance. Une clé de l’autre environnement reçoit 401 UNAUTHORIZED, avec un message qui nomme la bonne adresse :

test keys (lok_test_) only work on https://sandbox.localoge.com/api/v1/channel

(ou l’inverse pour une clé lok_live_ envoyée au sandbox). Voir Sandbox.

Le piège classique

Une variable d’environnement restée au test, et vous croyez travailler en production depuis trois jours. GET /ping renvoie le key_id employé : vérifiez-le au démarrage de votre service.

Portées

Une clé peut être limitée à ce dont vous avez besoin. Si des portées sont posées sur la vôtre, elles sont appliquées : une requête hors périmètre reçoit 403 FORBIDDEN avec la portée qui manque, nommée dans le message.

Portée	Ce qu’elle ouvre
properties:read / properties:write	Lire vos logements, les créer et les mettre à jour
availability:read / availability:write	Le calendrier de disponibilité
rates:read / rates:write	Les tarifs et les restrictions
reservations:read / reservations:write	Lire, créer, modifier, annuler
messages:read / messages:write	La conversation avec le voyageur
reviews:read	Les avis d’un logement
webhooks:read / webhooks:write	Votre URL de réception, les livraisons, leur relance et le test

Les routes du cycle de vie (POST …/pause, POST …/activate, DELETE /properties/{id}) relèvent de properties:write. GET /events et GET /webhooks/deliveries relèvent de webhooks:read ; POST /webhooks/deliveries/{id}/retry et POST /webhooks/test de webhooks:write. GET /conformance et les routes /sandbox/* sont ouvertes à toute clé valide, quelles que soient ses portées.

Treize portées en tout : ce sont les seules que l’espace développeur propose.

Une écriture emporte la lecture

availability:write vous permet aussi de relire le calendrier. Exiger les deux serait un piège de plus, pour aucun gain.

Aucune portée posée = aucune restriction

Une clé sans portées déclarées peut tout faire. C’est le cas par défaut.

Poser des portées vous-même

Dans votre espace développeur, la création d’une clé propose la liste des portées : cochez celles dont l’usage a besoin. Une clé de lecture pour un tableau de bord interne, une clé qui ne touche qu’au calendrier pour un service de synchronisation : chacune son périmètre, et une fuite ne coûte que ce périmètre-là.

GET /ping vous renvoie les portées de la clé employée. Un tableau vide veut dire « aucune restriction », pas « aucun droit ».

Une route non classée est refusée aux clés restreintes

Si une clé porte des portées et appelle une route que nous n’avons pas encore rattachée à une portée, la réponse est 403 FORBIDDEN avec le message this endpoint has no scope rule yet: contact us. Jamais une porte ouverte par défaut. Écrivez-nous en citant le request_id.

Rotation

Depuis l’espace développeur, le bouton Rotation d’une clé en crée une nouvelle, affichée une seule fois. L’ancienne continue de fonctionner pendant 7 jours, puis expire d’elle-même : le temps de déployer la nouvelle partout, sans interruption de service.

Pendant ces 7 jours, GET /ping vous dit quelle clé chaque serveur emploie encore (key_id). Quand plus aucun n’emploie l’ancienne, révoquez-la sans attendre l’échéance.

Révocation

Si vous pensez qu’une clé a fuité, révoquez-la depuis votre espace développeur (bouton Révoquer), ou écrivez-nous : la révocation est immédiate et définitive. Une clé révoquée renvoie 401 UNAUTHORIZED dès la requête suivante.