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, créez 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é

Les clés d’API sont en libre-service depuis le back-office. Un propriétaire ou copropriétaire peut les gérer dans Paramètres → Développeurs :

Ouvrez Paramètres → Développeurs et créez une nouvelle clé d’API.
Copiez le secret (sk_live_…) — il n’est affiché qu’une fois, à la création. Stockez-le en lieu sûr avant de quitter la page.
Envoyez-le comme jeton Bearer, comme indiqué ci-dessus.

Chaque clé est épinglée à une version de l’API à sa création et peut être révoquée à tout moment depuis le même écran. Un restaurant peut détenir jusqu’à 10 clés — gardez-en une par intégration pour pouvoir les faire tourner ou les révoquer individuellement.

Il n’y a pas d’environnement de bac à sable ou de test distinct : 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.)