Clés API

Une clé API est ce qu'un service externe présente pour prouver qu'il est autorisé à travailler sur votre projet. Chaque clé a un nom que vous choisissez, un statut, l'ensemble des permissions qui lui ont été accordées, une expiration, et une valeur complète qui n'est affichée qu'une seule fois. Depuis l'onglet Accès API d'un projet, vous créez une clé — en décidant au passage ce qu'elle peut atteindre et combien de temps elle dure —, consultez la liste de celles qui existent déjà, renommez ou désactivez une clé, et supprimez celle dont vous ne voulez plus.

Avant de commencer — Créer, modifier et supprimer des clés est réservé aux administrateurs du projet. Un autre membre ouvre l'onglet et consulte la liste, mais il n'a ni bouton Créer une clé API ni bouton Détail sur les lignes — et les pages qui se trouvent derrière le renvoient en arrière.

Remarque — Créer, modifier et supprimer se font tous dans un panneau qui glisse depuis la droite, par-dessus la liste. Le panneau porte le titre de l'action, un bouton de fermeture (✕) et un lien Voir en entier en bas. Le résultat s'écrit dans le panneau lui-même — vous n'êtes jamais envoyé sur une autre page. Le fermer — avec ✕, en cliquant sur la zone grisée à côté, ou en appuyant sur Échap — actualise la liste derrière, qui montre alors ce que vous venez de faire.

Créer une clé API

La clé complète n'existe sous une forme lisible que le temps d'un seul affichage de page. Prévoyez de la copier avant de commencer.

1. Ouvrez votre projet, puis l'onglet Accès API.
2. Cliquez sur Créer une clé API — le bouton au-dessus de la liste, ou celui du panneau Aucun accès API s'il s'agit de votre première clé.
3. Sur Créer une clé API, saisissez un Nom. Il vous sert à distinguer vos clés, comme le suggère la ligne d'aide : Exemple : Production, test, intégration. Jusqu'à 200 caractères.
4. Ouvrez Accès et choisissez Accès complet ou Accès restreint. La ligne d'aide indique la différence : L'accès complet autorise toutes les routes, actuelles et futures. L'accès restreint n'autorise que les permissions que vous choisissez.
5. Si vous avez choisi Accès restreint, remplissez le cadre Permissions qui apparaît sous le champ. Il comporte une ligne par partie de l'API que sert votre projet, chacune portant le nom de cette partie (product, category…), et chaque ligne propose Aucun accès, Lecture, Lecture et écriture et Écriture. Laissez une ligne sur Aucun accès pour en tenir la clé à l'écart.
6. Ouvrez Expiration et choisissez 30 jours, 90 jours, 365 jours ou N'expire jamais.
7. Cliquez sur Suivant.
8. La clé API a été créée. apparaît dans le panneau. Fermez-le.
9. La liste derrière s'actualise avec la nouvelle clé en haut, sa valeur complète dans un cadre en lecture seule sous son nom. Copiez-la maintenant.

Un email confirmant la création de la clé vous est envoyé.

Important — copiez cette clé maintenant, elle ne sera plus affichée par la suite. est écrit en rouge sous le cadre, et c'est à prendre au pied de la lettre : quitter la liste ou la recharger remplace la valeur complète par un aperçu du type sk-project-...a1b2, et rien ne permet de retrouver la clé complète. Si vous la perdez, supprimez la clé et créez-en une autre.

Remarque — Une clé sans nom est refusée avec Le nom de la clé API est obligatoire. — le panneau reste ouvert avec ce que vous avez saisi.

Remarque — Nom accepte jusqu'à 200 caractères et le champ vous arrête à cette limite. La limite compte des caractères, pas des octets : un nom accentué ou en écriture non latine dispose donc des 200 caractères et est enregistré exactement tel que vous l'avez saisi. Une valeur plus longue qui parvient tout de même au serveur est refusée avec Veuillez utiliser au maximum 200 caractères. en rouge, et aucune clé n'est créée.

Remarque — Le cadre Permissions n'apparaît qu'une fois Accès placé sur Accès restreint ; sur Accès complet, la clé atteint tout et il n'y a rien à choisir. Les lignes proposées sont les parties de l'API que sert votre projet : deux projets peuvent donc en afficher de différentes.

Remarque — Lecture et écriture sur une ligne accorde toutes les actions sur cette partie de l'API, y compris celles ajoutées plus tard. Lecture et Écriture n'accordent chacune qu'elles-mêmes : une clé réglée sur Écriture ne peut pas lire.

Important — Accès, Permissions et Expiration se choisissent une seule fois, à la création de la clé. Le panneau Détail les affiche mais ne permet pas de les changer. Pour élargir, restreindre ou prolonger une clé, créez-en une nouvelle et supprimez l'ancienne.

Astuce — L'encadré d'aide à côté du formulaire le résume sous Permissions et expiration : N'accordez que les permissions dont l'intégration a besoin, et définissez une expiration pour qu'une clé divulguée cesse de fonctionner d'elle-même. Expiration ajoute son propre avertissement — Une clé qui n'expire jamais ne peut être retirée qu'en la supprimant. Préférez une durée autour de laquelle planifier une rotation.

Remarque — Laisser Accès ou Expiration vide est refusé avec Choisissez un niveau d'accès pour cette clé. ou Choisissez une expiration pour cette clé., et choisir Accès restreint sans accorder une seule ligne est refusé avec Une clé restreinte a besoin d'au moins une permission, sinon toutes les routes la refusent. Le panneau reste ouvert avec ce que vous avez saisi et aucune clé n'est créée.

Consulter les clés de votre projet

1. Ouvrez votre projet, puis l'onglet Accès API.
2. Lisez la liste — une ligne par clé, avec ces colonnes :
   • Clé API — le nom que vous lui avez donné, puis sa valeur. C'est la valeur complète juste après la création, puis un aperçu des quatre derniers caractères ensuite.
   • Statut — Activé pour une clé qui fonctionne, Suspendu pour une clé qui a été désactivée. Le panneau Détail nomme ce même état Désactivée.
   • Permissions — Accès complet ou, pour une clé restreinte, une permission par ligne, écrite comme l'API la lit : product:read, category:write, product:* pour lecture et écriture.
   • Expiration — Jamais, ou la date à laquelle la clé cesse de fonctionner, suivie de (Expirée) une fois cette date passée.
   • Créée par — l'adresse email de la personne qui l'a créée.
   • Créé le — la date et l'heure de sa création.
3. Utilisez les boutons de pagination (Précédent / Suivant) pour parcourir une longue liste. Le compteur à côté indique les lignes affichées et le total, par exemple 1-50 | 63.

La ligne sous la liste — Les clés API permettent de connecter un service externe à ce projet. — est un rappel, pas un lien.

Remarque — Une clé toute neuve affiche Nouveau sur le seul affichage qui montre sa valeur complète, puis Activé à partir de l'affichage suivant.

Remarque — Un projet sans aucune clé affiche Aucun accès API et Aucune clé API n'a été créée sur ce projet. à la place de la liste.

Remarque — Les clés supprimées disparaissent de la liste pour de bon ; aucun filtre ni archive ne les fait revenir.

Important — Atteindre sa date d'expiration ne change pas le Statut d'une clé : la ligne affiche toujours Activé, avec (Expirée) à côté de la date. Les appels signés avec elle sont pourtant refusés. C'est dans la colonne Expiration que vous voyez la date approcher : surveillez-la et créez la clé de remplacement avant qu'elle n'arrive.

Renommer ou désactiver une clé

Désactiver est la façon réversible d'arrêter une clé : elle reste dans la liste et vous pouvez la réactiver.

1. Ouvrez l'onglet Accès API, puis cliquez sur Détail sur la ligne de la clé. Le panneau Détail s'ouvre sur Détail d'une clé API.
2. Modifiez le Nom, ou réglez le Statut sur Activée ou Désactivée.
3. Cliquez sur Enregistrer.

Vous voyez La clé API a été mise à jour. Fermez le panneau : la ligne affiche le nouveau nom et le nouveau statut.

Important — Désactiver une clé bloque immédiatement tous les appels qui l'utilisent. Tout ce qui signait ses requêtes avec cette clé cesse de fonctionner jusqu'à ce que vous la remettiez sur Activée.

Remarque — Nom obéit ici à la même limite de 200 caractères que dans le panneau de création, comptée de la même façon, et le nom saisi est enregistré en entier. Au-delà de la limite, Enregistrer ne fait rien et Veuillez utiliser au maximum 200 caractères. apparaît en rouge — le statut choisi n'est pas enregistré non plus : raccourcissez le nom et cliquez à nouveau sur Enregistrer.

Remarque — Le reste du panneau est en lecture seule : l'aperçu Clé API, les Permissions accordées à la clé, son Expiration, l'Utilisateur qui l'a créée, la date de Création et Dernière utilisation, la dernière fois qu'un appel l'a présentée. Dernière utilisation reste vide pour une clé qu'aucun appel n'a encore utilisée.

Remarque — Permissions affiche ici Accès complet, ou les mêmes lignes de permission que la liste (product:read, category:*…). Expiration affiche N'expire jamais, ou la date et l'heure de fin de la clé, suivies de (Expirée) une fois passées. Aucun des deux n'est modifiable : pour changer ce qu'une clé peut atteindre ou combien de temps elle dure, créez une clé de remplacement et supprimez celle-ci.

Supprimer une clé

La suppression est définitive. Désactivez d'abord la clé si vous voulez seulement l'arrêter pour un temps.

1. Ouvrez l'onglet Accès API, puis cliquez sur Détail sur la ligne de la clé.
2. Descendez jusqu'au cadre gris en bas, intitulé Supprimer cette clé API. — il prévient : La clé ne pourra plus être utilisée.
3. Cliquez sur Supprimer.
4. Fermez le panneau.

La clé API a été supprimée. apparaît dans le panneau, et les boutons Enregistrer et Supprimer disparaissent tous les deux : plus rien ne peut être fait sur la clé. La liste derrière s'actualise sans elle, et un email est envoyé à la personne qui avait créé la clé.