Clés d’API

Une clé d’API permet à un autre service, comme un outil de reporting ou une automatisation telle que Zapier, de lire les données de votre compte dans une application sans que personne ne se connecte. Chaque clé appartient à une application, ne peut faire que ce que vous choisissez, et fonctionne jusqu’à son expiration ou jusqu’à ce que vous la révoquiez.

Choisissez Paramètres du compte dans votre menu d’avatar, puis Accès à l’API, sous Intégrations, puis l’onglet Clés d’API. Seuls les Propriétaires et les Administrateurs du compte voient cet onglet. Dans une application comme Invoicing, Paramètres puis Accès à l’API vous mènent au même endroit.

L’onglet Clés d’API

Créer une clé

L’onglet Vos jetons, à côté

Quand vous ne pouvez pas créer de clés

Chaque application est listée avec ses clés. Si vous ne pouvez pas en créer une, l’écran en indique la raison :

• L’application n’offre pas encore d’API. Rien de votre côté ne peut changer cela.
• Votre forfait n’inclut pas l’accès à l’API. Un Propriétaire peut passer à un forfait qui l’inclut dans Facturation. Les clés que vous avez déjà cessent de fonctionner tant que votre forfait n’inclut pas l’accès à l’API, et reprennent lorsqu’il l’inclut de nouveau.

Créer une clé

1. Sous l’application, choisissez Créer une clé.
2. Donnez-lui un nom qui indique ce qui l’utilisera, comme Zapier, pour savoir plus tard quelle clé révoquer.
3. Sous Ce qu’elle peut faire, cochez uniquement ce dont le service a besoin. Pour Invoicing :
   • Voir vos clients (clients:read)
   • Voir vos factures (invoices:read)
   • Voir vos projets (projects:read)
4. Choisissez son expiration : jamais, dans 30 ou 90 jours, dans un an, ou à une date de votre choix. Elle cesse de fonctionner dès le début de cette journée.
5. Choisissez Créer une clé.

La clé n’est affichée qu’une fois. Copiez-la maintenant : vous ne la reverrez plus. Eddish n’en conserve qu’une empreinte, pas la clé elle-même : personne ne peut donc vous la montrer plus tard. Si elle est perdue, révoquez-la et créez-en une autre.

Ne laissez pas la clé dans des documents partagés ni dans du code que d’autres peuvent lire. Quiconque la possède peut faire ce qu’elle autorise.

Utiliser une clé

Envoyez la clé avec chaque requête dans l’en-tête Authorization :

GET /api/clients
Authorization: Bearer <your key>

Envoyez la requête à l’adresse propre de l’application, celle que vous utilisez pour ouvrir l’application.

• Une clé ne peut lire que le compte dans lequel elle a été créée.
• Une requête pour quelque chose que la clé n’a pas reçu est refusée avec 403.
• Une clé révoquée, expirée ou non reconnue est refusée avec 401.
• Chaque clé a une limite du nombre de requêtes qu’elle peut faire en peu de temps, définie par votre forfait. Une requête au-delà de la limite est refusée avec 429, et l’en-tête Retry-After indique combien de secondes attendre.

Révoquer une clé

Choisissez Révoquer à côté de la clé, puis Révoquer de nouveau pour confirmer. Elle cesse de fonctionner immédiatement et ne peut pas être réactivée. Une clé révoquée reste dans la liste, marquée Révoquée avec la date, pour que vous puissiez voir ce qui avait accès.

Chaque clé indique qui l’a créée et quand, quand elle expire et quand elle a été utilisée pour la dernière fois, au jour près. Une clé qui indique Jamais utilisée alors que vous pensiez qu’elle servait peut ne pas être configurée là où vous le croyez.

Jetons d’accès personnels des personnes

Sous les clés de chaque application, les Propriétaires et les Administrateurs voient les jetons d’accès personnels de tout le monde pour cette application : à qui appartient chacun, s’il peut seulement lire, quand il expire et quand il a été utilisé pour la dernière fois. Choisissez Révoquer à côté de l’un d’eux pour l’arrêter immédiatement. Vous ne voyez jamais les jetons eux-mêmes.

Un jeton d’accès personnel agit au nom de la personne qui l’a créé, avec son rôle, et accède à tout ce qu’elle peut faire. Une clé d’API agit pour le compte et n’accède qu’à ce qu’elle a reçu. Une clé envoyée ailleurs est refusée avec 403.