# Authentification > Les clés partenaires, les vingt-six scopes, ce que signifie une autorisation, et comment faire tourner une clé sans interruption. Source: https://developers.backresto.com/fr/docs/authentication Chaque requête à l'API Partenaire porte un seul identifiant d'accès, à l'endroit standard : ```http Authorization: Bearer brp_. ``` 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. | Moitié | Ce que c'est | Où elle peut apparaître | | --- | --- | --- | | `brp_` | Un identifiant public de la clé. | Vos journaux, un e-mail au support, la liste des clés sur ce site. | | `` | 256 bits d'aléa. | Votre gestionnaire de secrets, et l'en-tête `Authorization`. | 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 × scope 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 scopes**, et la grammaire vaut la peine d'être apprise une fois pour toutes : | Scope | Donne accès à | | --- | --- | | `:read` | L'une des [vingt-six collections](https://developers.backresto.com/fr/docs/collections) : `deliveries:read`, `delivery-pictures:read`, `cooling:read`, `temperature-records:read`, `traceability-labels:read` et ainsi de suite, un scope par collection. | Tous les scopes se terminent par `:read`. Il n'existe aucun scope 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 un. Une clé qui détient `deliveries:read` sur `restaurant-1` et `restaurant-2`, et `delivery-pictures:read` sur `restaurant-1` seulement, lit les photographies de livraison 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 scopes, 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 le scope 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 scopes, et [`GET /v1/restaurants/{id}/collections`](https://developers.backresto.com/fr/docs/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é](https://developers.backresto.com/fr/docs/access) 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 scopes. 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.