Authentification

L’API Service authentifie les requêtes avec une clé d’API, envoyée comme jeton Bearer dans l’en-tête Authorization.

GET /v1/reservations HTTP/1.1
Host: api.useservice.app
Authorization: Bearer sk_live_YOUR_SECRET_KEY

Avec curl :

curl https://api.useservice.app/v1/reservations \
  -H "Authorization: Bearer $SERVICE_API_KEY"

Les exemples de cette documentation lisent la clé depuis une variable d’environnement SERVICE_API_KEY plutôt que de la coder en dur — gardez votre vraie clé hors de l’historique du shell, des scripts et du contrôle de version.

Comment fonctionnent les clés

Les clés sont par restaurant. Une clé authentifie exactement un restaurant et ne renvoie jamais que les données de ce restaurant. Le restaurant est déterminé par la clé — vous ne transmettez jamais d’identifiant de restaurant.
Les clés sont secrètes. Une clé commençant par sk_live_ accorde un accès complet en lecture aux données de réservation et de clients d’un restaurant. Traitez-la comme un mot de passe.
Les clés sont réservées au serveur. N’intégrez jamais une clé dans un navigateur, une application mobile, un dépôt public ou tout code côté client. Utilisez-la uniquement depuis votre backend.
Les clés ne sont affichées qu’une fois. Le secret complet est affiché une seule fois, à la création de la clé. Seul un court suffixe (les 4 derniers caractères) est conservé et affiché par la suite, alors stockez la valeur complète de manière sécurisée dès la création. Si vous la perdez, demandez une nouvelle clé.
Plusieurs clés sont prises en charge. Un restaurant peut détenir plusieurs clés (par exemple, une par intégration), ce qui vous permet d’en faire tourner ou d’en révoquer une sans perturber les autres.

Obtenir une clé

L’API est en bêta. La gestion des clés en libre-service depuis le back-office est prévue mais pas encore disponible — pour l’instant, les clés sont fournies sur demande : contactez l’équipe Service et nous en générons une pour votre restaurant. Chaque clé est épinglée à une version de l’API à sa création.

Il n’y a pas d’environnement de bac à sable ou de test distinct dans cette version : toutes les clés sont en production (sk_live_…) et lisent vos vraies données de réservation et de clients via l’unique URL de base de production. Comme l’API est en lecture seule, les requêtes ne modifient jamais les données — mais traitez les données que vous lisez comme réelles.

Erreurs d’authentification

Une clé manquante, mal formée, révoquée ou inconnue renvoie 401 Unauthorized avec une enveloppe d’erreur. Il existe deux codes d’authentification :

auth_header_missing — aucun en-tête Authorization: Bearer … n’a été envoyé.
invalid_token — une clé a été envoyée mais elle est invalide, révoquée, expirée ou inconnue.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_token",
    "message": "The provided API key is invalid, revoked, or expired.",
    "doc_url": "https://docs.useservice.app/api/errors#invalid_token"
  }
}

(param est omis ici — aucun paramètre de requête n’est en cause.)