Clés API pour agents : read, write, publish, et un journal d'audit que vous consulterez vraiment

Donnez à chaque agent la clé Shager la plus restreinte possible pour sa mission : read pour le reporting, write pour la rédaction des brouillons, et publish uniquement pour l'étape qui programme les publications. Conservez les clés dans des variables d'environnement ou dans la configuration du client MCP, jamais dans les prompts. Révoquez-les et renouvelez-les depuis le tableau de bord des agents, et consultez son journal d'audit, qui recense chaque appel passé par un agent, au moins une fois par semaine tant qu'un nouvel agent est en rodage.

Voilà pour la règle. La suite de cet article en explique la logique et le fonctionnement, car une règle que personne ne comprend est contournée dès la première fois qu'elle dérange.

Que permet chaque scope ?

Chaque clé Shager porte un ou plusieurs de ces trois scopes. Chaque opération de l'API déclare le scope dont elle a besoin ; vous le trouverez sous la forme x-scope sur chaque opération du document OpenAPI. Les outils MCP sont les mêmes opérations : les mêmes règles s'appliquent donc via MCP.

Scope	Opérations
read	whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics
write	create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post
publish	schedule_post

Deux points de ce tableau méritent l'attention.

D'abord, publish ne contient qu'une seule opération, celle qui met le contenu en ligne sur les comptes des clients. Tout l'intérêt est de l'isoler. Un agent peut faire presque tout le travail, de l'import des médias à l'envoi des liens de validation en passant par la rédaction des légendes de chaque compte, sans jamais pouvoir mettre une publication en ligne sur une page.

Ensuite, cancel_post relève de write. Un agent de rédaction peut donc ramener une publication programmée à l'état de brouillon. C'est voulu : arrêter une erreur doit être plus facile que d'en commettre une.

Une clé utilisée sans le scope requis reçoit une erreur au format standard, { "error": { "code", "message" } }, avec un code HTTP 403. Les agents doivent signaler cette erreur plutôt que chercher un moyen de la contourner, et vos instructions permanentes doivent le préciser.

Faites défiler sur le côté pour voir tout le schéma

D'où viennent les clés ?

Il existe deux chemins.

Un humain crée la clé sur app.shager.ai/dashboard/agents, en choisissant les scopes. C'est le chemin habituel pour une agence qui ajoute un agent à un compte existant.

L'agent s'inscrit lui-même. Un agent sans compte appelle POST https://app.shager.ai/api/v1/agent/signup avec un agent_name et, idéalement, un contact_email pour joindre son humain. Il reçoit une api_key, affichée une seule fois, et une claim_url. Cette clé fonctionne immédiatement dans un bac à sable, qui permet de créer jusqu'à cinq espaces de travail, d'importer des médias, de créer des brouillons et de consulter. Elle ne permet ni de programmer ou de publier, ni de créer des liens de connexion client, ni d'envoyer des demandes de validation.

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'

Ces restrictions ne sont levées que lorsqu'un humain ouvre claim_url, se connecte et revendique l'organisation. C'est à ce moment qu'il décide si la clé de l'agent obtient aussi publish. Si personne ne la revendique, le bac à sable expire au bout de sept jours. La marche à suivre complète est publiée sur /auth.md, et le pas-à-pas se trouve dans notre article sur l'auto-inscription des agents et la revendication.

Le choix de conception derrière tout cela est simple : un agent peut explorer et préparer seul, mais la connexion de vrais comptes et la publication sur ces comptes passent toujours par une personne.

Comment les agents doivent-ils stocker et transmettre les clés ?

Les clés Shager sont des jetons porteurs (bearer tokens), envoyés sous la forme Authorization: Bearer shgr_live_.... La propriété qui définit un jeton porteur, selon la RFC 6750, c'est que quiconque le détient peut s'en servir. Rien d'autre ne prouve l'identité. Tout l'enjeu consiste donc à ne pas le laisser fuiter.

En pratique :

1. Des variables d'environnement, référencées dans la configuration. Claude Code prend en charge l'expansion ${VAR} dans les en-têtes de .mcp.json, d'après sa documentation MCP. Le fichier peut être versionné ; la clé reste dans l'environnement.
2. Jamais dans un prompt. Une clé collée dans une conversation finit dans les transcriptions et les logs, et parfois dans des conversations partagées.
3. Jamais dans le dossier d'un client. Si vous tenez des dossiers de contexte par client, les clés n'y ont pas leur place. Ces dossiers finissent partagés et compressés en archives.
4. Une clé par rôle d'agent. Une tâche de reporting, un agent de rédaction et une étape de programmation ne doivent pas partager la même clé. Si l'une fuite, vous n'en révoquez qu'une.

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}

Le serveur MCP de Shager accepte cet en-tête de clé API. Les clients qui se connectent plutôt via OAuth, comme un connecteur personnalisé dans Claude ou ChatGPT, offrent le même contrôle : une personne valide la connexion sur l'écran de consentement de Shager, la publication est une case à part, décochée par défaut, et la connexion apparaît dans le même journal d'audit. Notre article Shager et ChatGPT détaille la configuration dans ChatGPT.

Renouveler une clé sans interruption

Il faut renouveler les clés quand une personne qui y avait accès s'en va, quand une clé a pu être exposée, et selon un calendrier que vous êtes capable de tenir. Voici l'ordre qui évite toute coupure :

1. Créez une nouvelle clé avec les mêmes scopes dans le tableau de bord.
2. Mettez à jour la variable d'environnement là où tourne l'agent.
3. Lancez whoami avec la nouvelle clé pour vérifier qu'elle fonctionne et affiche les scopes attendus.
4. Révoquez l'ancienne clé.

La révocation s'applique à tous les appels passés avec cette clé, en MCP comme en REST.

Faites défiler sur le côté pour voir tout le schéma

Les limites de requêtes font partie de la sécurité

Chaque clé est limitée à 120 requêtes par minute. Un agent bien conçu n'en approche jamais : préparer tous les brouillons de la semaine pour un client représente quelques dizaines d'appels. Quand un agent reçoit malgré tout une erreur HTTP 429, c'est généralement le signe d'une boucle, un agent qui relance encore et encore le même appel en échec. Vos instructions doivent traiter la 429 comme un signal d'arrêt, pas comme une invitation à réessayer plus vite. Ralentir, signaler, et laisser un humain regarder.

Lire le journal d'audit

Le tableau de bord des agents affiche un journal d'audit de chaque appel d'agent. Il ne sert que si quelqu'un le lit. Voici ce qu'il faut surveiller pendant les premières semaines avec un nouvel agent :

1. Des appels inattendus. Un agent de reporting qui appelle create_post, c'est que ses instructions ou sa clé posent problème.
2. Une dérive entre espaces de travail. Des appels qui touchent un client sans rapport avec la tâche. C'est le signal d'alerte précoce de l'erreur entre clients décrite dans un agent, plusieurs clients.
3. Des rafales d'erreurs. Des 403 à répétition signifient que l'agent tente sans cesse une action hors de son scope. Corrigez les instructions, pas le scope.

Après quelques semaines sans incident, un coup d'œil rapide chaque semaine suffit.

FAQ

Un agent doit-il un jour détenir le scope publish ?

C'est possible, une fois que vous faites confiance à ses brouillons et que vous avez une étape de relecture, qu'il s'agisse de liens de validation client ou d'un relecteur interne. Une bonne pratique consiste à réserver publish à une clé distincte, utilisée uniquement par une courte étape de programmation scriptée : l'agent qui écrit n'est alors pas celui qui publie.

Que devient la clé d'un agent quand le bac à sable est revendiqué ?

L'organisation passe à l'humain, et la clé continue de fonctionner à l'intérieur. Au moment de la revendication, l'humain choisit si cette clé peut aussi programmer et publier. Il peut la révoquer ou en créer de nouvelles depuis le tableau de bord à tout moment.

Peut-on limiter une clé à l'espace de travail d'un seul client ?

Les scopes limitent ce qu'une clé peut faire, pas l'espace de travail sur lequel elle agit. Séparez les clients grâce aux espaces de travail, à un contexte propre à chaque client et à l'habitude de résoudre l'espace de travail par son nom avant chaque écriture, et utilisez des clés distinctes par rôle pour que la révocation reste chirurgicale.

Pour aller plus loin

Si vous configurez votre premier agent, le point d'entrée des agents présente les deux façons d'obtenir une clé. Commencez avec une clé write et n'ajoutez publish que lorsque les brouillons l'ont mérité.