Authentication

Depuis le 10 octobre 2026, l’API d’Actero, c’est le serveur MCP : https://actero.fr/api/mcp. Ton IA (Claude, ChatGPT, Cursor…) et ton développeur appellent les mêmes outils, avec les mêmes droits et le même journal. Deux façons de s’authentifier, plus une clé publique qui n’est pas une authentification.

Vue d’ensemble

Qui	Comment	Durée	Pour quoi faire
Ton IA	OAuth 2.1 + PKCE, `Authorization: Bearer mcp_at_…`	1 h, renouvelée automatiquement (renouvellement de 30 jours, tournant)	Claude, ChatGPT, Cursor, VS Code, Le Chat…
Un développeur, un outil d’automatisation	Jeton développeur, `Authorization: Bearer mcp_pat_…`	30, 90 ou 365 jours	Scripts, Zapier, Make, n8n, ton back-office
La bulle de ta boutique	Clé publique `ak_…` dans l’adresse (`?api_key=`)	Jusqu’à suppression	Afficher la bulle et lui faire parler à l’agent, rien d’autre

La session du tableau de bord (jeton Supabase) n’ouvre plus le serveur MCP, et un ancien jeton mcp_… rangé avec les clés de la bulle non plus : ils ont été remplacés le 10 octobre 2026. Si ton IA était déjà connectée, elle te demandera de te reconnecter.

Appeler l’API

Le serveur parle MCP (protocole 2025-11-25, transport HTTP « streamable », sans session) : une requête JSON-RPC 2.0 par appel. tools/call marche sans initialize.

curl https://actero.fr/api/mcp \
  -H "Authorization: Bearer $ACTERO_JETON" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://actero.fr/api/mcp \
  -H "Authorization: Bearer $ACTERO_JETON" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"actero_statistiques_lire","arguments":{"periode":"7j"}}}'

const res = await fetch('https://actero.fr/api/mcp', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ACTERO_JETON}`,
    'Content-Type': 'application/json',
    Accept: 'application/json, text/event-stream',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: { name: 'actero_activite_lister', arguments: { filtre: 'escalades', limite: 10 } },
  }),
})
const { result } = await res.json()
// result.structuredContent : la réponse de l'outil ; result.isError : un refus expliqué.

tools/list donne chaque outil, sa description en français et le schéma de ses paramètres. Les listes se paginent par curseur.

Actions qui demandent une confirmation

Une action qui part chez un client (répondre depuis « À traiter »), qui supprime ou qui coupe l’agent ne se fait pas au premier appel. L’outil rend etat: "a_confirmer", un aperçu et un code confirmation valable 10 minutes. Rappelle le même outil avec exactement les mêmes paramètres et ce code pour exécuter. Un code ne sert qu’une fois ; des paramètres différents le rendent invalide.

Jetons développeur (`mcp_pat_…`)

Pour un script ou un outil d’automatisation.

Tableau de bord → IA et API → L’API, pour un développeur → Créer un jeton.
Donne-lui un nom (ex. Zapier), choisis ses droits (lecture seule, ou lecture et modifications) et sa durée (30, 90 ou 365 jours).
Copie-le tout de suite : il n’est affiché qu’une fois. Actero n’en garde qu’une empreinte.

Réservé au propriétaire et aux managers de la boutique, dès la formule Starter. Si la formule repasse sous Starter, le jeton est suspendu (403 insufficient_plan).
Le jeton agit avec les droits de la personne qui l’a créé, relus à chaque appel : si elle quitte l’équipe, le jeton ne sert plus.
Révoquer (même page) coupe le jeton immédiatement.

Connexion d’une IA (OAuth)

Tu n’as rien à coder : colle l’adresse du serveur dans ton IA (voir l’onglet IA et API, partie Connecter ton IA). Pour un client MCP que tu développes :

métadonnées : https://actero.fr/.well-known/oauth-protected-resource/api/mcp (RFC 9728, resource = https://actero.fr/api/mcp) et https://actero.fr/.well-known/oauth-authorization-server (RFC 8414) ;
inscription par document de métadonnées client (CIMD) ou dynamique (RFC 7591) ; redirections exactes (https, boucle locale sur n’importe quel port) ;
PKCE S256 obligatoire ; portées lecture, ecriture, offline_access ;
la personne choisit sa boutique sur l’écran Actero et décide d’« Autoriser les modifications » ou non ;
jeton d’accès d’une heure, renouvellement de 30 jours qui change à chaque usage ; un renouvellement réutilisé coupe la connexion ;
révocation : POST https://actero.fr/revoke (RFC 7009), ou Déconnecter dans la page.

Chaque action d’une IA est écrite dans le journal de la boutique (« Ce que ton IA a fait »), sans donnée de client final ; une modification de réglage s’y annule pendant 7 jours.

Clé publique de la bulle (`ak_…`)

Elle se colle dans ton thème (data-actero-key) : elle est publique, lisible par n’importe quel visiteur. Elle ne donne accès à aucune donnée : elle sert seulement à afficher ta bulle et à transmettre les messages de tes clients à l’agent.

curl -X POST "https://actero.fr/api/engine/webhooks/widget?api_key=ak_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Où est ma commande #1234 ?", "session_id": "essai-1"}'

Cet appel est réel : l’agent répond comme dans la bulle, et le message compte dans ton quota de tickets. La clé passe dans l’adresse, pas dans le corps.

Ne colle jamais un jeton mcp_… dans ton thème : c’est un secret. Et une clé ak_… n’ouvre jamais le serveur MCP.

Erreurs

Code	Réponse	Cause
401	`{ "error": "unauthorized" }` + en-tête `WWW-Authenticate: Bearer … resource_metadata="…"`	Jeton absent, expiré ou révoqué ; ton IA relance la connexion
403	`{ "error": "insufficient_plan" }`	Jeton développeur sur une formule sous Starter
403	`{ "error": "origine_refusee" }`	Appel depuis un navigateur dont l’origine n’est pas permise
429	`{ "error": "too_many_requests" }` + en-tête `Retry-After`	Plus de 300 requêtes par minute pour une même connexion
503	`{ "error": "temporarily_unavailable" }`	Vérification impossible un instant : réessaie
200 + `result.isError`	`{ "erreur": { "code", "message", "suite" } }`	Refus d’un outil : `role`, `lecture_seule`, `formule`, `limite_plan`, `quota`, `introuvable`, `invalide`, `conflit`, `prerequis`, `confirmation_*`, `trop_de_requetes`, `indisponible`, `interne`

Bonnes pratiques

Un jeton par outil : tu peux en révoquer un sans couper les autres.
Range le jeton dans une variable d’environnement (ACTERO_JETON), jamais dans un dépôt ni un fichier public.
Commence en lecture seule ; n’ajoute les modifications que pour un outil qui en a besoin.
Ne logge jamais le jeton en clair.

Référence

Endpoints

Authentication

Vue d’ensemble

Appeler l’API

Actions qui demandent une confirmation

Jetons développeur (`mcp_pat_…`)

Connexion d’une IA (OAuth)

Clé publique de la bulle (`ak_…`)

Erreurs

Bonnes pratiques

​Vue d’ensemble

​Appeler l’API

​Actions qui demandent une confirmation

​Jetons développeur (mcp_pat_…)

​Connexion d’une IA (OAuth)

​Clé publique de la bulle (ak_…)

​Erreurs

​Bonnes pratiques

Vue d’ensemble

Appeler l’API

Actions qui demandent une confirmation

Jetons développeur (`mcp_pat_…`)

Connexion d’une IA (OAuth)

Clé publique de la bulle (`ak_…`)

Erreurs

Bonnes pratiques