MADATA / DEV documentation développeur English madata.africa

Clés d’API & OAuth

Deux mécanismes, un seul modèle de jeton sous-jacent. L’OAuth 2.1 par la passerelle pour les assistants IA ; la clé Bearer pour votre code et les outils qui se configurent par fichier.

01La clé MCP

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.

Ne pas confondre

La clé MCP ne sert que sur le serveur MCP. L’API de données a sa propre clé, créée dans les préférences de l’espace.

02Créer une clé

Dans le portail MADATA : Mia → onglet MCP → Créer une clé. Une clé connecte un outil externe à MADATA sans mot de passe ni double authentification : traitez-la comme un secret.

Qui peut créer une clé

Le propriétaire et les Administrateurs MADATA de l’espace. Pour relier un assistant en OAuth, aucune clé n’est nécessaire : tout utilisateur qui a accès à Mia peut le faire (voir plus bas).

Nom
Libre : sert à retrouver la clé dans la liste.
Durée
1 mois, 3 mois, 6 mois, 1 an, ou permanente.
Portée
Lecture seule (défaut) ou Lecture + écriture.
Agir au nom de
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"}}}'

Une clé s’utilise toujours sur l’adresse de son espace, https://<espace>.madata.app/mia/mcp, jamais sur mcp.madata.africa.

04Portées

PortéeOutils visibles
read_onlyUniquement les outils qui n’écrivent pas.
full_accessTous les outils, lecture et écriture.
customUniquement les outils d’une liste blanche, définie côté espace. Sans liste, aucun outil.

La portée est encore bridée par le mode d’accès de l’utilisateur : une connexion full_access portée par un utilisateur « Lecture seule » ne pourra pas écrire. Elle se change à tout moment depuis la carte Connexions et clés du portail.

05Révoquer / supprimer

Depuis la carte Connexions et 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. Pour une connexion passée par la passerelle, l’une ou l’autre coupe aussitôt la liaison.

06OAuth 2.1 par la passerelle

Claude, ChatGPT, Le Chat et Claude Code se connectent à https://mcp.madata.africa/mcp en OAuth 2.1 avec PKCE S256. Aucun identifiant client à préparer : ils s’enregistrent seuls.

Endpoint (sur mcp.madata.africa)Rôle
GET /.well-known/oauth-protected-resourceRFC 9728 : resource: "https://mcp.madata.africa/mcp", scopes_supported: ["mcp"].
GET /.well-known/oauth-authorization-serverRFC 8414 : endpoints, authorization_code + refresh_token, S256, iss dans la réponse (RFC 9207).
POST /oauth/registerEnregistrement dynamique de client (RFC 7591). Client public, sans secret. Les documents de métadonnées client (CIMD) sont aussi acceptés pour ChatGPT et Claude.
GET /oauth/authorizeVérifie la demande puis redirige vers la page MADATA d’autorisation. Demande valable 15 minutes.
POST /oauth/tokenÉchange authorization_code (PKCE S256 obligatoire, code à usage unique valable 5 minutes) ou refresh_token.

Sur la page MADATA, l’utilisateur se connecte (e-mail et mot de passe, Google ou Microsoft, code de double authentification s’il est activé), choisit l’espace s’il en a plusieurs, puis autorise. Son mot de passe reste chez MADATA : l’assistant ne reçoit qu’un accès révocable. Tout utilisateur qui a accès à Mia peut relier un assistant, avec ses propres droits.

Le jeton remis est une clé MCP de l’espace : elle apparaît dans Connexions et clés sous le nom de l’assistant, par exemple « ChatGPT (mcp.madata.africa) », en lecture + écriture bornée par le mode d’accès de l’utilisateur. Seule son empreinte est conservée par la passerelle.

  • Durée de vie : le jeton d’accès vaut 30 jours. Le rafraîchissement remet une nouvelle clé et supprime l’ancienne, sans action de l’utilisateur.
  • Portée tenue : chaque rafraîchissement relit l’état de la clé dans l’espace. Une restriction est conservée, une clé coupée coupe la liaison.
  • Jeton rejoué : un jeton de rafraîchissement déjà remplacé, présenté de nouveau plus de 60 secondes après, coupe la liaison.
  • Nom vérifié : le nom et le logo de ChatGPT ou de Claude ne s’affichent que si l’adresse de retour est bien la leur. Sinon, la page indique « (non vérifié) ».
  • Connexion protégée : 10 échecs par adresse en 15 minutes verrouillent la connexion ; une demande admet 5 codes de double authentification faux au plus.

07OAuth 2.1 sur l’espace

Chaque espace garde aussi son propre serveur d’autorisation, pour un client qui vise directement https://<espace>.madata.app/mia/mcp :

Endpoint (sur l’espace)Rôle
GET /.well-known/oauth-protected-resourceRFC 9728 : métadonnées de la ressource.
GET /.well-known/oauth-authorization-serverRFC 8414 : endpoints, authorization_code + refresh_token, S256.
POST /mia/mcp/oauth/registerEnregistrement dynamique (RFC 7591) : renvoie un client_id mcp_…. 64 Ko et 30 demandes par minute au plus.
GET /mia/mcp/oauth/authorizePage de consentement. 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 vaut 30 jours et un refresh_token (mrt_…) le renouvelle en silence. Présenté de nouveau plus de 60 secondes après sa rotation, un jeton de rafraîchissement désactive la clé. 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 et consentement protègent toujours le flux.

08Cycle de vie & sécurité

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