Clés API personnelles

Une clé API permet à un programme — un script, un outil de BI, le connecteur MCP d’un assistant IA… — d’utiliser Tickr en votre nom via l’API publique. Chaque clé :

• vous appartient et ne vaut que pour un seul workspace ;
• porte un rôle qui ne peut jamais dépasser le vôtre ;
• peut expirer automatiquement ;
• n’est affichée qu’une seule fois, au moment de sa création.

Tout membre actif d’un workspace peut créer ses propres clés, quel que soit son rôle.

Qui peut créer quel type de clé ?

La fenêtre de création ne propose que les rôles autorisés pour votre rôle dans le workspace choisi :

Votre rôle dans le workspace	Rôles de clé proposés	Rôle proposé par défaut
Propriétaire, Administrateur	Administrateur, Responsable de projet, Analyste, Membre	Membre
Responsable de projet	Responsable de projet, Analyste, Membre	Membre
Analyste	Analyste (lecture seule)	Analyste
Membre	Membre	Membre

Une clé ne peut jamais avoir le rôle Propriétaire : même en cas de fuite, elle ne permet ni de supprimer le workspace ni d’en transférer la propriété.

Le rôle Membre est celui recommandé pour le connecteur MCP : la clé peut alors saisir et modifier vos temps, sans accès aux saisies des autres.

Créer une clé

1. Dans la barre latérale, section Gestion, ouvrez Intégrations.
2. Dans la carte Clés d’API, cliquez sur Créer une clé.
3. Renseignez la fenêtre :
   • Workspace — le workspace auquel la clé donnera accès. Vous pouvez choisir n’importe lequel de vos workspaces, sans avoir à basculer dessus.
   • Rôle de la clé — voir le tableau ci-dessus. Une aide s’affiche sous le champ : Recommandé pour le connecteur MCP (rôle Membre) ou Clé en lecture seule (rôle Analyste).
   • Expiration — 30 jours, 90 jours (par défaut), 1 an ou Jamais.
   • Nom — obligatoire (200 caractères au plus). Choisissez un nom qui dit à quoi sert la clé, par exemple « Connecteur MCP — portable ».
4. Cliquez sur Créer une clé.

Si vous êtes Analyste, seul le rôle Analyste est proposé :

Copier la clé — une seule fois

Juste après la création, la fenêtre affiche la clé complète (elle commence par tkr_live_) avec l’avertissement « Cette clé ne sera affichée qu’une seule fois. Copiez-la maintenant. »

1. Cliquez sur le bouton de copie à droite de la clé (un message Copié confirme).
2. Collez-la immédiatement dans l’outil qui l’utilisera (ou dans votre gestionnaire de secrets).
3. Fermez la fenêtre avec Fermer.

Tickr ne conserve qu’une empreinte de la clé : personne ne peut la réafficher, ni vous ni un administrateur. Si vous l’avez perdue, révoquez-la et créez-en une autre.

Si votre rôle a changé pendant que la fenêtre était ouverte, Tickr abaisse le rôle de la clé au vôtre et l’indique sous la clé : « Rôle effectif de la clé : … ».

L’email de confirmation

À chaque création, le propriétaire de la clé reçoit un email « Une nouvelle clé API a été créée sur votre compte Tickr » (lorsque l’envoi d’emails est configuré sur l’instance). Il rappelle le nom de la clé, le workspace, le rôle, la date de création et l’expiration — jamais la clé elle-même. Si vous n’êtes pas à l’origine de cette création, suivez le lien de l’email pour révoquer la clé et changez votre mot de passe.

Lire la liste des clés

La carte Clés d’API liste vos clés actives, tous workspaces confondus. Pour chaque clé :

• son nom, puis le workspace et le rôle de la clé ;
• Créée le … ;
• Expire le …, Sans expiration, ou Expirée en rouge ;
• la dernière utilisation (ou Jamais). Pour les clés créées à partir de cette version, elle est précédée du début de la clé (par exemple tkr_live_ab12cd…), propre à chaque clé : il vous aide à reconnaître celle qu’utilise un outil. Les clés plus anciennes n’affichent que leur dernière utilisation.

La date de dernière utilisation est mise à jour au plus toutes les 5 minutes : elle sert à repérer les clés dormantes, pas à suivre chaque appel.

Une clé expirée reste dans la liste (avec la mention Expirée) mais elle ne fonctionne plus et ne compte plus dans la limite de 10 clés. Révoquez-la pour faire le ménage.

Révoquer une clé

Cliquez sur l’icône de corbeille (Révoquer) au bout de la ligne. Une fenêtre de confirmation « Révoquer la clé « nom de la clé » ? » s’ouvre : elle rappelle que les applications qui utilisent cette clé cesseront immédiatement de fonctionner et que l’action est irréversible. Si vous révoquez la clé d’un autre membre (vue Propriétaire / Administrateur), elle indique aussi son titulaire : « Clé de nom du membre. »

• Révoquer confirme : la clé disparaît de la liste et tout programme qui l’utilise est refusé dès son appel suivant.
• Annuler (ou la touche Échap) referme la fenêtre sans rien changer.

Une clé révoquée ne peut pas être réactivée.

Pour remplacer une clé (rotation), créez d’abord la nouvelle, mettez à jour votre outil, puis révoquez l’ancienne.

Vue des propriétaires et administrateurs

Si vous êtes Propriétaire ou Administrateur d’un workspace, la liste contient aussi les clés de tous les membres de ce workspace. Chacune indique son titulaire (Propriétaire : nom du membre), et vous pouvez la révoquer — par exemple au départ d’un collaborateur ou en cas de doute sur une fuite. Vous ne voyez jamais la clé elle-même.

Les autres rôles ne voient que leurs propres clés ; les clés des autres membres leur sont invisibles.

Quand une clé cesse-t-elle de fonctionner ?

Sans action de votre part, une clé est désactivée quand :

• sa date d’expiration est atteinte ;
• vous quittez le workspace (Quitter ce workspace) ou en êtes retiré par un administrateur : vos clés de ce workspace sont révoquées ;
• le workspace est supprimé : toutes ses clés sont révoquées ;
• votre mot de passe est réinitialisé via le lien reçu par email — que vous l’ayez demandé (Mot de passe oublié ?) ou qu’un administrateur vous ait envoyé un lien de réinitialisation : toutes vos clés, dans tous vos workspaces, sont révoquées et toutes vos sessions sont fermées. L’email « Votre mot de passe Tickr a été modifié » le précise (« Par sécurité, vos N clés API ont été révoquées ; recréez-les depuis la page Intégrations. ») ;
• votre rôle devient incompatible avec celui de la clé : une clé Analyste cesse de fonctionner si vous devenez Membre, et inversement. Créez alors une nouvelle clé.

En revanche :

• changer votre mot de passe depuis votre Profil (Changer le mot de passe) ne révoque ni vos clés ni vos sessions ;
• un changement de rôle (hors cas Analyste ↔ Membre ci-dessus) ne révoque pas la clé, mais elle n’agit jamais au-delà de votre rôle actuel : la clé Administrateur d’une personne redevenue Membre agit comme une clé Membre.

Limites et messages d’erreur

Situation	Message affiché
Vous avez déjà 10 clés actives (non révoquées, non expirées) dans ce workspace	« Tu as atteint 10 clés actives dans ce workspace. Révoque une clé inutilisée d’abord. »
Plus de 10 tentatives de création en une heure (tous workspaces confondus, tentatives refusées comprises)	« Trop de clés créées récemment. Réessaie plus tard. »
Le nom contient un retour à la ligne, une tabulation…	« Le nom ne doit pas contenir de caractères de contrôle (retours à la ligne, tabulations…). »
Le rôle demandé est incompatible avec le vôtre (Analyste ↔ Membre)	« Ce rôle de clé n’est pas compatible avec ton rôle dans ce workspace. »

Le bouton Créer une clé de la fenêtre reste grisé tant que le nom est vide.

Bonnes pratiques

• Une clé par usage (un script, un outil, un poste), avec un nom explicite : vous pourrez révoquer l’une sans casser les autres.
• Le rôle le plus bas suffisant : Membre pour saisir vos temps, Analyste pour de la lecture seule.
• Une expiration plutôt que Jamais, sauf besoin réel.
• Ne collez jamais une clé dans un ticket, un chat ou un dépôt de code ; si c’est arrivé, révoquez-la.

Pour les développeurs

Format de l’en-tête, codes d’erreur, quotas : voir la documentation Authentication de l’API (en anglais).