Clés d’API & OAuth

Deux mécanismes d’authentification, un seul modèle de jeton sous-jacent. La clé Bearer pour les scripts et ChatGPT/Gemini ; l’OAuth 2.1 pour les connecteurs natifs de Claude et Mistral.

01La clé d’API d’espace

C’est la clé d’API que MADATA expose sur chaque espace. Format : mia_ suivi de 64 caractères hexadécimaux (256 bits d’entropie). Elle est stockée hachée en SHA-256 : le serveur ne peut pas la ré-afficher.

Un même jeton porte l’identité d’un utilisateur de l’espace et une portée. Chaque appel s’exécute sous cet utilisateur.

02Créer une clé

Dans MADATA : Mon profil → Sécurité du compte → Clés API → Créer une clé. Une clé API connecte un outil externe à MADATA sans mot de passe ni double authentification : traitez-la comme un secret.

Qui peut créer une clé

Réservé aux Administrateurs MADATA de l’espace. La liste des utilisateurs éligibles est proposée dans le formulaire.

Nom: Libre : sert à retrouver la clé dans la liste.
Durée: 1 mois, 3 mois, 6 mois, 1 an, ou permanente. Par défaut : 365 jours.
Portée: Lecture seule (défaut) ou Lecture et écriture.
Utilisateur: L’utilisateur de l’espace dont la clé porte les droits (le propriétaire de l’espace par défaut).

La clé n’est affichée qu’une seule fois, à la création. Copiez-la immédiatement ; elle ne sera plus jamais lisible.

03Utiliser la clé

bashappel authentifié

curl -s https://<espace>.madata.app/mia/mcp \
  -H "Authorization: Bearer mia_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_kpi","arguments":{"period":"month"}}}'

L’URL de l’espace s’affiche à côté de la clé dans le portail. Elle a toujours la forme https://<espace>.madata.app/mia/mcp.

04Portées

Portée	Outils visibles
`read_only`	Uniquement les outils de lecture (`kind = read`).
`full_access`	Tous les outils, lecture et écriture.
`custom`	Uniquement les outils d’une liste blanche (configurable côté espace).

La portée est encore bridée par le mode d’accès de l’utilisateur : une clé full_access portée par un utilisateur « Lecture seule » ne pourra pas écrire.

05Révoquer / supprimer

Depuis la liste des clés : révoquer désactive la clé sans la supprimer (l’historique reste) ; supprimer l’efface définitivement. Une clé révoquée renvoie 401 au prochain appel.

06OAuth 2.1 (connecteurs natifs)

Claude.ai et Mistral Le Chat n’acceptent pas de clé statique : ils se connectent en OAuth 2.1 avec PKCE S256. Le serveur MADATA implémente le profil d’autorisation MCP :

Endpoint	Rôle
`GET /.well-known/oauth-protected-resource`	RFC 9728 : métadonnées de la ressource (`resource_name: "Madata"`, `scopes_supported: ["mcp"]`).
`GET /.well-known/oauth-authorization-server`	RFC 8414 : endpoints, `grant_types` `authorization_code` + `refresh_token`, `code_challenge_methods_supported: ["S256"]`.
`POST /mia/mcp/oauth/register`	Enregistrement dynamique de client (RFC 7591) : renvoie un `client_id` `mcp_…`.
`GET /mia/mcp/oauth/authorize`	Page de consentement de marque (Madata ↔ Claude). Connexion à l’espace requise.
`POST /mia/mcp/oauth/authorize/decision`	Émet un code d’autorisation à usage unique, protégé CSRF.
`POST /mia/mcp/oauth/token`	Échange `authorization_code` (PKCE S256 obligatoire, `plain` refusé) ou `refresh_token`.

Le jeton d’accès émis est une vraie clé d’API : elle apparaît dans la liste des clés de l’espace, révocable de la même façon. Un refresh_token (mrt_…) permet le renouvellement silencieux. Reconnecter le même client_id désactive la clé précédente de ce client.

Redirections de confiance

Pour claude.ai, claude.com, console.anthropic.com, chatgpt.com, chat.openai.com, platform.openai.com, le client est ré-enregistré à la volée si son client_id mis en cache n’existe plus côté serveur (base recréée). PKCE + consentement admin protègent toujours le flux.

Réservé aux administrateurs

Le consentement OAuth est gaté : seul un Administrateur MADATA de l’espace (ou l’administrateur système) peut autoriser un connecteur.

07Cycle de vie & sécurité

Chaque appel s’exécute avec les droits de l’utilisateur porteur de la clé, jamais plus.
La clé est stockée hachée : elle n’est jamais ré-affichée.
Expiration vérifiée à chaque appel ; une clé expirée renvoie 401.
Le préfixe mrt_ du jeton de rafraîchissement le rend inutilisable comme clé d’accès.
Chaque tools/call est journalisé (voir Journalisation).