Comptes de service¶

Un compte de service est un membre de votre organisation qui n'est pas une personne, mais un programme : une intégration, un script qui tourne la nuit, un autre système qui appelle OS. Tout ce qu'une personne peut faire dans OS, un compte de service peut le faire via l'API, décidé exactement de la même façon. Cette page s'adresse aux administrateurs : ceux qui ont le rôle d'administrateur de l'organisation.

Une clé peut exactement ce que peut son compte de service, et rien de plus. Qui a une clé agit comme le compte de service. Si vous donnez peu de droits à un compte de service, ses clés donnent aussi peu de droits. Ne donnez donc à un compte de service que ce dont le programme a vraiment besoin.

À l'écran¶

Ouvrez Gestion des utilisateurs, choisissez Comptes de service et parcourez :

La liste. Vous voyez vos comptes de service. Choisissez Créer un nouveau compte de service pour en créer un.
Créer. Remplissez Nom et, si vous le souhaitez, Description, choisissez les rôles, groupes et valeurs d'attribut qu'il reçoit (vous ne pouvez donner que ce que vous avez vous-même) et choisissez Créer un compte de service.
Clés. Ouvrez le compte de service et choisissez l'onglet Clés. Choisissez Créer une nouvelle clé API, remplissez Nom de la clé API et Date d'expiration et choisissez Créer une clé API. L'écran montre le Secret une seule fois, avec l'Identifiant client et l'Adresse du jeton : conservez-le tout de suite. Pour chaque clé, vous voyez le statut, son expiration, sa dernière utilisation et ses avertissements. Quand une clé expire dans les 14 jours, les administrateurs de l'organisation reçoivent aussi une notification dans OS et par e-mail, une fois par date d'expiration. L'ancienne copie d'une clé remplacée n'avertit pas.
Rotation. Sur une clé active, choisissez Faire une rotation, indiquez la nouvelle date d'expiration et le Chevauchement en heures et confirmez. L'écran montre le nouveau secret une seule fois. Seul celui qui a tout ce qu'a le compte de service obtient ce bouton.
Révoquer. Sur une clé, choisissez la corbeille et confirmez. La clé ne fonctionne alors plus.
Droits. L'onglet Droits montre les rôles, groupes et valeurs d'attribut du compte de service. Choisissez Ajouter des droits pour en donner, ou retirez-en un ; vous ne pouvez donner et retirer que ce que vous pouvez vous-même.
Accès. L'onglet Accès montre, par type d'élément, ce que le compte de service peut faire (Voir, Utiliser, Modifier, Supprimer), donc aussi ce que peut faire celui qui détient sa clé. Regardez ici avant de créer une clé.
Désactiver et supprimer. En haut de la page, choisissez Désactiver (ou Activer) ou Supprimer.

Créer un compte de service¶

Choisissez un nom (unique dans votre organisation) et, si vous le souhaitez, une description de son usage.
Choisissez les rôles, groupes et valeurs d'attribut qu'il reçoit, comme pour une invitation. Vous ne pouvez donner que ce que vous avez vous-même (pourquoi).
Le compte de service est actif tout de suite. Personne n'a d'invitation à accepter.

Un compte de service figure dans la même liste de membres que les personnes, avec les mêmes rôles, groupes et attributs. Seul qui gère les comptes de service les modifie, de la même façon que pour une personne ; un administrateur des personnes voit un compte de service dans la liste, mais n'y modifie rien. Un compte de service ne compte pas comme dernier administrateur : une organisation garde toujours une personne avec le rôle d'administrateur.

Ce qu'un compte de service ne peut pas faire¶

Ce qu'une personne ne fait que pour elle-même, un compte de service ne peut pas le faire : définir des préférences, se faire effacer et accepter une invitation. OS refuse cela avec 403. Un compte de service est géré et supprimé par un administrateur.

Clés¶

Un programme se connecte avec une clé. Un compte de service peut avoir plusieurs clés (cinq au maximum en même temps par défaut), chacune avec son propre nom.

Créez une clé avec un nom et une date d'expiration. Elle est obligatoire et se situe au plus un an dans le futur.
OS affiche le secret de la clé une seule fois, avec l'identifiant client et l'adresse où le programme demande un jeton. Conservez tout de suite le secret dans un endroit sûr ; OS ne le montre plus jamais.
Après quelques secondes, la clé fonctionne.

Seul qui a tout ce qu'a le compte de service peut lui créer une clé. Ainsi, personne ne peut obtenir par une clé plus de droits qu'il n'en a déjà.

Le programme demande un jeton avec l'identifiant client et le secret, et envoie ce jeton à OS :

curl -s -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

Un jeton est valable cinq minutes ; le programme en demande ensuite un nouveau.

Remplacer sans interruption¶

Faites une rotation de la clé : OS crée une nouvelle clé avec un nouveau secret, et l'ancienne continue de fonctionner pendant un chevauchement (24 heures par défaut, 30 jours au maximum). Mettez le nouveau secret dans le programme avant la fin du chevauchement.

Retirer, expirer et avertissements¶

Une clé retirée ne fonctionne plus à partir de la requête suivante.
Une clé expirée ne fonctionne plus à partir de sa date d'expiration.
Pour chaque clé, vous voyez quand OS l'a vue utilisée pour la dernière fois (à cinq minutes près). OS avertit pour une clé qui expire dans les 14 jours, qui n'a pas été utilisée depuis 30 jours, ou qui n'a jamais été utilisée une semaine après sa création.

Utiliser via MCP¶

Votre propre agent qui parle MCP peut travailler avec OS en tant que compte de service, avec les droits du compte : chaque opération de l'API d'OS devient alors un outil. Ouvrez le compte de service ; sur l'onglet Général, Utiliser via MCP affiche :

l'Adresse MCP, où l'agent envoie ses appels ;
l'Adresse du jeton, où l'agent obtient un jeton ;
Obtenir un jeton et Lister les outils : deux exemples à copier.

Utilisez l'ID client d'une clé de l'onglet Clés et le secret de cette clé. Mettez le secret à la place de YOUR_CLIENT_SECRET et le jeton de la première étape à la place de ACCESS_TOKEN :

curl -s -X POST '<adresse du jeton>' \
  -d grant_type=client_credentials \
  -d client_id='<ID client>' \
  -d client_secret='YOUR_CLIENT_SECRET'

curl -s -X POST '<adresse MCP>' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Un jeton est valable cinq minutes ; obtenez-en ensuite un nouveau. Si le compte de service n'a aucune clé active, la carte indique d'en créer une d'abord. Tant que les apps d'IA sont sur Désactivé dans l'organisation, chaque appel de l'agent est refusé jusqu'à ce qu'un administrateur l'active (Travailler depuis des apps d'IA) ; la carte le dit aussi.

Ce qu'un compte de service peut faire et ce qu'il a fait¶

Pour chaque compte de service, vous voyez par type d'élément ce qu'il peut faire. Dans le journal d'audit, vous voyez ce qu'il a fait et ce qui a été fait avec le compte de service et ses clés. Les secrets ne figurent jamais dans le journal d'audit.

Désactiver et supprimer¶

Désactiver : à partir de la requête suivante, OS refuse au compte de service tout dans l'organisation, sous chaque clé ; seul GET /api/v1/me répond encore, sans adhésion. Réactiver rend les mêmes clés de nouveau utilisables.
Supprimer : définitif. Toutes les clés sont retirées. Ce que le compte de service a créé dans les fonctions d'IA reste à l'organisation, sauf si vous choisissez de l'effacer.

Quand OS refuse¶

401 : la clé est retirée ou expirée, ou le jeton appartient à un autre client.
403 : vous donnez un rôle, un groupe ou une valeur que vous n'avez pas vous-même, ou vous créez une clé pour un compte de service qui a plus que vous ; le message indique quoi.
409 : le nom est déjà utilisé, le compte de service a déjà le nombre maximal de clés, ou le compte de service a été modifié entre-temps.
422 : une date d'expiration manquante, passée ou trop éloignée.

Via l'API¶

POST /api/v1/organisations/{id}/service-accounts avec name et, au choix, description, roles, groups et attributes, comme pour une invitation.
GET, PATCH (avec If-Match) et DELETE /api/v1/organisations/{id}/service-accounts/{account_id}.
POST /api/v1/organisations/{id}/service-accounts/{account_id}/keys avec label et expires_at ; la réponse contient client_id, client_secret et token_endpoint.
POST …/keys/{key_id}/rotate avec expires_at et overlap_hours ; DELETE …/keys/{key_id} retire une clé.
GET /api/v1/organisations/{id}/memberships/{account_id}/access affiche ce qu'il peut faire ; GET /api/v1/organisations/{id}/audit-events?actor={account_id} ce qu'il a fait.