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.
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.
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é
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ée | Outils visibles |
|---|---|
read_only | Uniquement les outils qui n’écrivent pas. |
full_access | Tous les outils, lecture et écriture. |
custom | Uniquement 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-resource | RFC 9728 : resource: "https://mcp.madata.africa/mcp", scopes_supported: ["mcp"]. |
GET /.well-known/oauth-authorization-server | RFC 8414 : endpoints, authorization_code + refresh_token, S256, iss dans la réponse (RFC 9207). |
POST /oauth/register | Enregistrement 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/authorize | Vé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-resource | RFC 9728 : métadonnées de la ressource. |
GET /.well-known/oauth-authorization-server | RFC 8414 : endpoints, authorization_code + refresh_token, S256. |
POST /mia/mcp/oauth/register | Enregistrement dynamique (RFC 7591) : renvoie un client_id mcp_…. 64 Ko et 30 demandes par minute au plus. |
GET /mia/mcp/oauth/authorize | Page 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.
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/callest journalisé (voir Journalisation).