Authentification

Chaque requête à l'API Partenaire porte un seul identifiant d'accès, à l'endroit standard :

Authorization: Bearer brp_<prefix>.<secret>

Il n'y a pas d'autre schéma. Pas de clé en paramètre d'URL, pas de basic auth, pas de cookie. Une requête sans cet en-tête, ou avec une valeur mal formée, répond 401 avant que quoi que ce soit d'autre ne soit évalué.

Ce qu'est une clé

Une clé a deux moitiés séparées par un point.

BackResto stocke le préfixe et une empreinte à clé du secret. Le secret lui-même n'est pas stocké et ne peut pas être récupéré — ni par vous, ni par le support, ni depuis la base de données. S'il est perdu, révoquez la clé et créez-en une autre.

Autorisations : restaurant × portée

Une clé n'est pas « un compte avec des permissions ». C'est une liste d'autorisations explicites, chacune étant une paire :

Il y a vingt-six portées, et la grammaire vaut la peine d'être apprise une fois pour toutes :

Toutes les portées se terminent par :read. Il n'existe aucune portée partenaire qui écrive, et on ne peut pas en créer : le côté écriture de cette API appartient à l'application BackResto, et une clé partenaire est structurellement incapable d'en détenir une.

Une clé qui détient deliveries:read sur restaurant-1 et restaurant-2, et delivery-images:read sur restaurant-1 seulement, lit les photographies du premier restaurant et obtient 403 pour le second. C'est une configuration prise en charge, pas une erreur — certaines intégrations veulent les enregistrements sans les images.

Demandez ce que vous utilisez. Vingt-six portées, ce n'est pas un menu qu'on coche de haut en bas : le restaurant lit la liste avant d'y consentir, et une demande qui veut tout met plus de temps à passer qu'une demande portant sur les quatre collections que votre produit lit réellement.

Trois modes d'échec, volontairement distincts :

• 404 — la clé ne détient aucune autorisation pour ce restaurant. L'API ne dit pas à un appelant non autorisé si un restaurant existe.
• 403 — la clé détient une autorisation pour ce restaurant, mais pas la portée dont cet endpoint a besoin.
• 401 — entre autres choses, une clé qui n'a plus aucune autorisation. Une clé dépouillée de sa dernière autorisation cesse de s'authentifier plutôt que de répondre du vide.

Pour voir ce qu'une clé détient réellement, demandez-le-lui : GET /v1/restaurants liste les restaurants avec leurs portées, et GET /v1/restaurants/{id}/collections liste les collections qu'elle ouvre.

Qui peut en émettre une

Nous, sur demande, et seulement pour des restaurants qui y ont consenti. Voyez Obtenir une clé pour ce qu'il faut envoyer et ce qui revient.

Les autorisations sont fixées au moment où la clé est provisionnée et ne changent que par une nouvelle demande. Il n'existe aucun chemin — ni pour vous ni pour nous — qui élargisse une clé sans que le restaurant y consente à nouveau.

Expiration et révocation

Une clé n'expire pas d'elle-même, sauf si vous en avez demandé une qui le fait. Elle reste valide jusqu'à sa révocation.

La révocation est immédiate : la requête suivante avec cette clé répond 401, la même réponse qu'obtient une clé inconnue ou expirée. Elle ne peut pas être annulée, et n'a pas besoin de l'être — un remplacement est une nouvelle clé, pas une clé restaurée.

Faire tourner une clé sans interruption

Une intégration peut détenir deux clés actives à la fois, la rotation ne demande donc aucune fenêtre de maintenance. Demandez-nous une rotation et voici l'ordre dans lequel elle se déroule :

1. Nous émettons une seconde clé avec les mêmes restaurants et les mêmes portées.
2. Vous déployez le nouveau secret, et vous nous dites quand il est actif partout.
3. Nous vérifions que l'ancienne clé a cessé d'être utilisée — nous voyons quand chaque clé s'est authentifiée pour la dernière fois, et c'est ce signal qui rend l'étape 4 sûre.
4. Nous révoquons l'ancienne.

Faites tourner vos clés au rythme que vous choisissez, et lancez la demande quelques jours avant la date à laquelle vous voulez voir l'ancienne clé disparaître : les étapes 2 et 3 sont à coordonner entre vous et nous, et tout l'intérêt de l'ordre ci-dessus est que rien ne soit jamais mort, même brièvement.

Hygiène

• Stockez-la dès son arrivée et supprimez l'e-mail. Une fois cela fait, le secret existe dans exactement deux endroits : votre gestionnaire de secrets, et l'en-tête Authorization.
• Une clé par déploiement, pas une par société. Une clé de préproduction divulguée ne devrait jamais devenir un incident de production, et une révocation ne devrait jamais faire tomber plus que la chose qui a fuité.
• Ne nous envoyez jamais le secret — pas dans un ticket, pas pour identifier une clé. Le préfixe public la nomme sans ambiguïté et peut s'écrire n'importe où sans risque.
• Surveillez les 401 dans votre propre supervision. Une clé qui se met à échouer a été révoquée, et la réponse est une conversation, pas une boucle de nouvelles tentatives.