> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification MCP Didit : Connexion avec Didit (OAuth)

> Authentifiez le serveur MCP Didit via OAuth 2.1 avec PKCE, enregistrement dynamique, scopes et rôles pour connecter vos clients.

Le MCP Didit s'authentifie avec **Se connecter avec Didit** (OAuth 2.1). Il agit en tant qu'**utilisateur** Didit avec les autorisations de votre rôle dans la console — **il n'y a pas de mode avec une clé API**.

## Se connecter avec Didit

Le serveur hébergé (`https://mcp.didit.me/mcp`) est un **serveur de ressources** OAuth 2.1. La **Business Console de Didit** (`business.didit.me`) est le **serveur d'autorisation** qui héberge l'écran de consentement et délivre les tokens. Votre client MCP exécute automatiquement le flux standard :

**1. Découvrir**

Le client envoie une requête POST à `/mcp` sans token et reçoit un code `401` avec un en-tête `WWW-Authenticate: Bearer` dont le paramètre `resource_metadata` pointe vers les métadonnées de ressource protégée (RFC 9728) :

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Ce document indique la ressource (`https://mcp.didit.me/mcp`), le serveur d'autorisation (`https://business.didit.me`) et les scopes pris en charge. Le même document est également servi à la racine de l'origine, `https://mcp.didit.me/.well-known/oauth-protected-resource`, pour les clients effectuant d'abord une requête à cet emplacement.

**2. S'enregistrer (enregistrement dynamique du client)**

Le client lit les métadonnées du serveur d'autorisation à l'adresse `https://business.didit.me/.well-known/oauth-authorization-server` et, s'il n'a pas encore d'identifiant client, s'enregistre auprès du `registration_endpoint` (RFC 7591). Il n'y a rien à préconfigurer de votre côté : les clients locaux disposant d'une URL de rappel loopback ou native (Claude Code, Cursor, MCP Inspector) et les clients hébergés dans le cloud avec une URL de rappel examinée (Claude) s'enregistrent tous deux de cette façon. Une URL de rappel distante non examinée par Didit est refusée avec l'erreur `invalid_redirect_uri` ; un opérateur doit d'abord enregistrer ce client.

**3. Autoriser (PKCE)**

Le client ouvre `https://business.didit.me/authorize` avec un challenge PKCE S256. Vous vous connectez (ou vous vous inscrivez) et voyez exactement quelles autorisations sont demandées. Les clients sont publics : l'endpoint de token n'accepte aucun secret client (`token_endpoint_auth_methods_supported` vaut `none`), PKCE est donc ce qui lie le code au client.

**4. Consentir**

Vous approuvez. La console génère une session pour cette application, liée aux scopes que vous avez approuvés, et renvoie un code d'autorisation, que le client échange au niveau du `token_endpoint` contre un token d'accès et un token d'actualisation.

**5. Appeler les outils**

Le client envoie le token d'accès avec chaque requête. Le serveur MCP le valide par introspection de token (RFC 7662) auprès du service d'authentification Didit (les tokens sont opaques, et non des JWT), lit les autorisations de votre organisation à partir de la réponse d'introspection et agit en votre nom pour la durée de cette requête.

### Scopes

Les métadonnées de ressource annoncent trois scopes. L'écran de consentement affiche ceux demandés par un client en langage clair :

| Scope | Droits accordés |
| - | - |
| `didit:management` | Gérer votre espace de travail : `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` et `analytics`. |
| `didit:verification` | Exécuter et examiner les vérifications : `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` et `analytics`. |
| `didit:staff` | Réservé aux comptes du personnel Didit. Il ne débloque rien pour un compte standard, et la version open source ne définit aucun outil réservé au personnel. |

Les deux scopes incluent `analytics`. La gestion de `lists` nécessite `didit:management` ; l'accès à `blocklist` nécessite `didit:verification`.

La [référence des outils](https://docs.didit.me/fr/integration/mcp/tools.md) liste le scope dont relève chaque outil. Les scopes que vous approuvez sont inclus dans le token et appliqués côté serveur, de sorte qu'une application connectée uniquement avec `didit:verification` est refusée sur l'interface de gestion, même si votre propre rôle l'autoriserait. Le serveur d'autorisation reconnaît également les scopes OpenID (`openid profile email`) ; une connexion qui ne demande que ceux-ci peut déterminer qui vous êtes, et rien d'autre.

Les autorisations effectives d'une application correspondent à l'**intersection** des scopes approuvés et de votre rôle dans la console — jamais plus étendues que la moins étendue des deux.

Pour créer une session de vérification avec `didit_session_create`, vous devez disposer du scope `didit:verification` **et** d'un rôle comportant `create:sessions` ou `write:sessions`. Le rôle **Développeur** inclut `create:sessions`. Approuver `didit:management` seul ne permet pas la création de session, même si votre rôle dispose de l'autorisation requise.

### Rôles et autorisations

Le token hébergé **vous** représente, de sorte que l'agent peut intervenir sur **chaque organisation à laquelle vous appartenez** au sein d'une seule connexion ; les outils multi-applications (`didit_session_search`, `didit_analytics`, `didit_context_get` et les autres outils `*_search`) agrègent automatiquement l'ensemble de ces organisations.

Votre **rôle est toujours appliqué** par le backend Didit, par organisation. Chaque outil correspond à une chaîne d'autorisation backend (par exemple `write:sessions` pour `didit_session_update_status`, `delete:sessions` pour `didit_session_delete`) ; la [référence des outils](https://docs.didit.me/fr/integration/mcp/tools.md) l'indique pour chaque outil. Le serveur vérifie également cette autorisation avant d'envoyer la requête, à l'aide des autorisations figurant dans la réponse d'introspection pour votre organisation :

* En mode `enforce`, un outil que votre rôle ne peut pas exécuter est exclu de `tools/list`, et tenter de l'appeler renvoie une erreur `missing_scope` qui précise l'autorisation manquante (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* En mode `shadow` (valeur par défaut du serveur), chaque outil est listé et l'appel est transmis au backend, qui répond par un code `403` lorsque le rôle ne dispose pas de l'autorisation ; le verdict est uniquement consigné dans le journal d'audit du serveur.

Dans les deux cas, le serveur MCP n'accorde jamais plus que ce que votre rôle dans la console autorise déjà. Un rôle `READER` peut lister et lire ; un `OWNER` ou un `ADMIN` peut écrire et supprimer.

### Durée de vie du token

Une application approuvée obtient sa propre session, distincte de la session du navigateur à partir de laquelle vous l'avez approuvée. Les tokens d'accès ont une courte durée de vie ; le client les actualise de manière transparente avec le token d'actualisation (`grant_types_supported` inclut `refresh_token`), et une actualisation conserve les scopes de l'application tout en restant liée à celle-ci. Si une actualisation échoue (par exemple après avoir déconnecté l'application), le client réexécute **Se connecter avec Didit** lors de l'appel suivant.

Se déconnecter de la console ne déconnecte pas les applications connectées, et déconnecter une application ne vous déconnecte jamais nulle part.

### Déconnecter une application

**1. Depuis la console**

**Settings → Authentication → Connected apps** répertorie toutes les applications que vous avez approuvées, avec leur nom enregistré et les autorisations qui leur ont été accordées. **Disconnect** met immédiatement fin à l'accès de cette application : son token d'accès et son token d'actualisation cessent tous deux de fonctionner, et rien d'autre n'est affecté.

**2. Depuis l'application (RFC 7009)**

Un client peut révoquer son propre accès en envoyant le token au `revocation_endpoint` du serveur d'autorisation, indiqué dans les métadonnées sur `https://business.didit.me/.well-known/oauth-authorization-server`. Comme l'exige la RFC 7009, un appel réussi renvoie `200`, que le token soit encore actif ou non, la réponse n'indique donc jamais si un token était valide. Un code `503` signifie que la révocation n'a pas pu être appliquée : considérez le token comme toujours valide et réessayez.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **Pourquoi pas de clé API ?** Chaque outil MCP appelle les endpoints de la console associés à l'utilisateur (`/organization/{org}/application/{app}/…`), qui autorisent un token Bearer avec des privilèges par rôle et **rejettent `x-api-key`**. Une clé API d'application sert à appeler l'[API REST](https://docs.didit.me/openapi-25.json) directement depuis votre propre backend (par ex. pour créer des sessions) — pas pour ce MCP. `didit_org_list_api_keys` affiche les métadonnées des clés avec les valeurs masquées ; l'outil qui révèle une clé brute est masqué sur le connecteur hébergé.

***

## Connexion depuis chaque client

Chaque client exécute le même flux ; seule la manière dont vous lui fournissez l'URL diffère.

> [tab] Claude
>
> Utilisez le lien profond affiché par la Business Console sur sa page d'intégration. Il ouvre claude.ai avec la boîte de dialogue **Add custom connector** préremplie :
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Confirmez, puis complétez **Log in with Didit**. Claude Desktop utilise la même URL sous **Settings → Connectors → Add custom connector**. Détails dans [Connecter Claude](https://docs.didit.me/fr/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Exécutez ensuite `/mcp` dans Claude Code pour lancer la connexion dans le navigateur.

> [tab] Cursor
>
> `~/.cursor/mcp.json` :
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor s'enregistre automatiquement et ouvre le navigateur lors de la première utilisation.

> [tab] Client générique
>
> Dirigez n'importe quel client HTTP compatible avec Streamable HTTP et OAuth 2.1 vers `https://mcp.didit.me/mcp`. Il doit :
>
> 1. `POST /mcp`, recevoir `401` et lire `resource_metadata` depuis `WWW-Authenticate`.
> 2. Récupérer `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`, puis les métadonnées du serveur d'autorisation sur `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. S'enregistrer auprès du `registration_endpoint` s'il n'a pas d'identifiant client.
> 4. Exécuter le flux de code d'autorisation avec PKCE (S256) auprès de l'`authorization_endpoint`, puis échanger le code auprès du `token_endpoint`.
> 5. Envoyer `Authorization: Bearer <access_token>` à chaque `POST /mcp`.
>
> Les clients sans prise en charge d'OAuth peuvent être placés derrière `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, qui réalise les étapes 1 à 5 pour eux.

***

## Échecs d'authentification

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

Une erreur `401` renvoyée par `/mcp` signifie que le token est manquant, expiré ou a été révoqué — le client doit rafraîchir le token ou relancer **Log in with Didit**.

Une erreur `403` ou une erreur `missing_scope` sur un outil *spécifique* signifie généralement soit que votre **rôle** ne dispose pas de cette autorisation (par ex. un rôle `READER` tentant une écriture), soit que la connexion a été approuvée **sans le scope** nécessaire à cet outil — et non que l'ensemble de la connexion est interrompu. Se reconnecter et approuver les deux scopes résout le second cas ; le premier nécessite une modification de rôle.

Si tous les outils échouent, vérifiez **Settings → Authentication → Connected apps** dans la console : une application qui y a été déconnectée doit être de nouveau approuvée.

***

> [card] [Référence des outils](https://docs.didit.me/fr/integration/mcp/tools.md)
>
> Ce que fait chaque outil, son scope et son autorisation de rôle.

> [card] [Avancé](https://docs.didit.me/fr/integration/mcp/advanced.md)
>
> Rôles, comportement multi-applications et auto-hébergement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.