Jetons API

Les jetons API permettent aux utilisateurs et aux comptes de service d'appeler l'API Forra de façon programmatique. Chaque jeton est créé avec un nom et une ou plusieurs portées choisies dans une liste fixe — il n'y a pas d'éditeur de chemins/verbes bruts dans l'interface.

Prérequis

• Tout utilisateur peut créer un jeton API personnel pour lui-même.
• Le rôle Administrateur de l'organisation est requis pour créer un jeton de compte de service.

1. Les portées restreignent, elles n'accordent jamais

Les portées d'un jeton constituent un plafond sur l'accès de son propre propriétaire, et non un octroi distinct de capacité. Un jeton ne peut rien faire que son propriétaire ne pourrait déjà faire avec sa propre session. Cela signifie que deux conditions doivent toujours être réunies pour qu'une automatisation fonctionne :

• L'utilisateur ou le compte de service doit détenir le rôle requis par l'action visée (par exemple, le rôle Administrateur de l'organisation pour les actions d'administration).
• Le jeton doit porter la portée correspondante.

Sélectionner une portée que le propriétaire ne peut pas utiliser est sans danger — le jeton est simplement incapable d'atteindre cette surface, exactement comme si la portée n'avait pas été sélectionnée.

2. Portées disponibles

Portée	Ce qu'elle permet
Lecture de votre profil	Lire vos propres préférences, votre prompt personnalisé, vos services connectés, votre utilisation et vos coûts. Sélectionnée par défaut.
Modification de votre profil	Modifier vos préférences et votre prompt personnalisé. Votre prompt personnalisé influence les réponses de tous vos assistants.
Discussion et conversations	Discuter avec les assistants et gérer les conversations utilisées par ce jeton. Ne peut pas lister l'historique des conversations.
Lecture de toutes les conversations	Lire tout votre historique de conversations, y compris celles que ce jeton n'a pas créées. Ne peut pas envoyer de messages.
Projets	Créer et gérer des projets, et y organiser vos conversations.
APIs compatibles OpenAI et Anthropic	Utiliser les points d'accès compatibles OpenAI et Anthropic. Affichée seulement si au moins une de ces intégrations est activée pour votre organisation.
Lecture des assistants	Lister les assistants et lire leur configuration, leurs compétences, leurs fichiers et leurs données.
Gestion des assistants	Créer, modifier et supprimer des assistants, y compris exécuter leurs fonctions et émettre des jetons d'application intégrée. Sensible.
Générer du contenu IA directement	Générer des images, de l'audio, de la vidéo et de l'analyse d'images directement par l'API.
Bases de connaissances	Créer et gérer les bases de connaissances et leurs documents.
Tâches et automatisations	Créer, exécuter et gérer les automatisations, y compris les automatisations planifiées.
Flux de travail	Créer, exécuter et déboguer des flux de travail.
Mémoire	Consulter, créer et supprimer la mémoire utilisée par les assistants pour personnaliser leurs réponses.
Compétences	Consulter et gérer les compétences, y compris la compilation des compétences d'un assistant.
Lecture de l'annuaire	Consulter la liste des utilisateurs, des groupes et des équipes de l'organisation.
Administration de l'organisation	Accès administratif complet à l'organisation. Sensible — n'accordez ceci qu'à un jeton qui automatise réellement l'administration.

Certaines portées n'apparaissent que si la fonctionnalité correspondante est activée pour votre organisation. Masquer une portée n'a aucun effet sur les jetons déjà créés lorsqu'elle était visible — leur comportement ne change pas.

3. Trois distinctions à connaître

• « Discussion et conversations » ne peut pas lister votre historique de conversations. Elle peut envoyer des messages et relire une conversation dont elle connaît déjà l'identifiant, mais elle ne peut pas énumérer tout ce que vous avez déjà dit. Utilisez « Lecture de toutes les conversations » pour cela.
• « Générer du contenu IA directement » n'est pas nécessaire pour que les assistants produisent des images ou de l'audio pendant une conversation. Cela se produit en interne et ne nécessite aucune permission supplémentaire. N'accordez cette portée qu'à un jeton qui appelle lui-même les points d'accès image/audio/vidéo.
• « Modification de votre profil » peut réécrire votre prompt personnalisé, ce qui modifie les réponses de tous vos assistants — traitez-la avec la même prudence que toute autre portée sensible.

4. Créer un jeton

Allez dans Paramètres → Sécurité → Jetons API → Créer. Entrez un nom, sélectionnez les portées dont le jeton a besoin, choisissez une expiration, restreignez éventuellement les assistants et les services externes, puis confirmez. La valeur du jeton est affichée une seule fois — copiez-la immédiatement, car elle ne pourra plus être révélée par la suite.

La création est refusée si aucune portée en plus de celle par défaut n'est sélectionnée — un jeton API qui ne peut que s'identifier lui-même est rarement ce que vous souhaitez.

5. Restriction des assistants

Lors de la création d'un jeton, vous pouvez limiter les assistants auxquels il a accès :

Mode	Effet
Tous les assistants (par défaut)	Le jeton atteint tous les assistants accessibles à son propriétaire.
Aucun assistant	Le jeton ne peut appeler aucun point d'accès assistant. Les conversations non liées à un assistant restent accessibles.
Restreint à des assistants spécifiques	Le jeton ne peut opérer que sur les assistants sélectionnés. Les appels vers les autres assistants sont refusés. Les conversations appartenant à d'autres assistants sont également refusées.

Un jeton sans restriction d'assistant se comporte exactement comme auparavant. Les conversations non liées à un assistant restent accessibles même lorsque le jeton est restreint ou défini sur aucun assistant.

La liste des jetons affiche Aucun assistant ou Restreint à N assistant(s) lorsque l'accès n'est pas illimité.

6. Services externes

Lors de la création d'un jeton, vous pouvez contrôler quels services externes (intégrations OAuth) il peut utiliser :

Mode	Signification
Tous les services externes	Le jeton peut utiliser tous les services externes configurés pour le locataire.
Aucun service externe (par défaut pour les nouveaux jetons avec portées)	Le jeton ne peut appeler aucun service externe.
Restreint à des services spécifiques	Le jeton ne peut utiliser que les services sélectionnés.

L'accès aux services externes est déjà appliqué par le système de jetons ; le formulaire de création permet seulement de choisir quels services sont stockés sur le jeton.

La liste des jetons affiche Aucun service externe ou N service(s) externe(s) lorsque l'accès n'est pas illimité.

7. Expiration

Chaque jeton nouvellement créé a une expiration choisie dans une liste fixe de préréglages :

Préréglage	Durée
1 mois	~30 jours
3 mois	~90 jours
6 mois (par défaut)	~180 jours
12 mois	~365 jours
Sans expiration	N’expire jamais

La valeur par défaut est 6 mois. Un jeton divulgué cesse de fonctionner de lui-même à l’expiration, au lieu de rester valide jusqu’à ce que quelqu’un s’en aperçoive et le révoque.

Les jetons qui portent une portée sensible (Modification de votre profil, Lecture de toutes les conversations, Administration de l’organisation) ne peuvent pas être définis sur Sans expiration. L’option est désactivée dans le formulaire de création lorsqu’une de ces portées est sélectionnée.

La liste des jetons affiche la date d’expiration de chaque jeton, ou N’expire pas lorsqu’aucune n’a été définie.

Les jetons existants créés avant l’introduction de l’expiration ne sont pas touchés — ils restent sans expiration. Les automatisations qui s’appuyaient sur des jetons de longue durée devront prévoir une rotation une fois que les nouveaux jetons commenceront à expirer.

8. Limites connues

• L'accès en lecture à un assistant ne peut pas être séparé de l'accès en lecture à ses données stockées — la portée « Lecture des assistants » accorde les deux ensemble. La restriction d'assistants peut tout de même limiter quels assistants un jeton atteint, mais au sein d'un assistant autorisé la lecture des données stockées n'est pas séparable de la lecture de la configuration.

9. Jetons hérités

Les jetons créés avant l'existence des portées affichent une étiquette Accès complet (héritage) plutôt qu'une liste de portées, car leurs droits n'ont jamais été enregistrés comme des portées. Considérez cette étiquette comme un avertissement, pas comme une fonctionnalité : un tel jeton dispose d'un accès non restreint. Révoquez-le et créez un nouveau jeton avec des portées à sa place.

Les jetons hérités n'ont également aucune restriction d'assistant — ils atteignent tous les assistants accessibles à leur propriétaire.