> ## Documentation Index > Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt > Use this file to discover all available pages before exploring further. # Authentification OAuth > Comment le serveur MCP Qwairy authentifie les connexions avec OAuth 2.1 et PKCE. Le serveur MCP Qwairy utilise **OAuth 2.1 avec PKCE** pour sécuriser l’authentification. Vos identifiants ne sont jamais partagés avec les clients IA : seul un jeton d’accès sécurisé et limité à des scopes l’est. ## Fonctionnement ```mermaid theme={null} sequenceDiagram participant User participant Client as MCP Client participant Auth as Qwairy Auth participant MCP as Qwairy MCP User->>Client: Start conversation Client->>Auth: Authorization request (with PKCE) Auth->>User: Login prompt User->>Auth: Sign in with Qwairy account Auth->>Client: Authorization code Client->>Auth: Exchange code for token Auth->>Client: User-scoped access token Client->>MCP: API request with access token MCP->>Client: Data response ``` La plupart des clients MCP gèrent ce flux automatiquement. Il vous suffit de cliquer sur « Authorize » quand cela vous est demandé : aucune équipe à choisir, aucun jeton à gérer à la main. La connexion est **rattachée à l’utilisateur** : elle peut lire chaque workspace éligible au MCP auquel vous avez accès directement ou par héritage depuis une équipe parente. ## Points de terminaison OAuth | Point de terminaison | URL | | - | - | | Découverte | `https://mcp.qwairy.co/.well-known/oauth-authorization-server` | | Enregistrement dynamique du client | `https://auth.qwairy.co/register` | | Autorisation | `https://auth.qwairy.co/authorize` | | Jeton | `https://auth.qwairy.co/token` | | Révocation | `https://auth.qwairy.co/revoke` | Les clients MCP récents découvrent ces points de terminaison à partir de l’URL du serveur. Indiquez seulement `https://mcp.qwairy.co` : le client récupère la configuration OAuth via le point de découverte. ## Scopes disponibles Ne demandez que les scopes nécessaires : | Scope | Description | | - | - | | `read:brands` | Voir la liste des marques suivies sur ce compte (noms des marques et domaines principaux). | | `read:visibility` | Voir les indicateurs de visibilité, les scores GEO et les tendances des marques suivies selon les fournisseurs IA. | | `read:competitors` | Voir les concurrents détectés dans les réponses IA, leurs classements, leur sentiment et leur évolution dans le temps. | | `read:sources` | Voir les domaines et URL tiers que les fournisseurs IA citent comme sources dans leurs réponses. | | `read:prompts` | Voir les questions et prompts suivis sur les fournisseurs IA, avec leur texte, leur statut et leurs Tags. `get_prompt_answers` inclut des extraits de réponse limités aux 500 premiers caractères. | | `read:answers` | Voir le texte complet et les métadonnées des réponses IA collectées pour les prompts suivis (texte, fournisseur, citations, sentiment). | | `read:topics` | Voir les groupes de Topics, la performance des mots-clés et la ventilation de la visibilité par Topic. | | `read:pitch-audits` | Lister et lire les rapports d’audit de prospection terminés ou en cours des workspaces agence auxquels vous avez accès. | | `read:measure` | Voir les analytics hors IA des intégrations connectées : performance de recherche, trafic référent IA, conversions et valeur configurées, synthèses conservées de l’activité des crawlers IA. | Si aucun scope n’est précisé, tous les scopes de lecture sont accordés par défaut. Si l’un des scopes demandés n’est pas reconnu, toute la demande d’autorisation est rejetée avec `invalid_scope`. `read:measure` et `read:pitch-audits` sont des scopes plus récents. Les connexions OAuth existantes doivent se reconnecter et autoriser à nouveau l’accès pour utiliser leurs outils. Les scopes d’un jeton déjà émis ne sont jamais étendus en silence. ## Cycle de vie des jetons Le flux OAuth émet un unique **jeton d’accès rattaché à l’utilisateur** : le même type de jeton qu’un jeton d’accès personnel (`qw-usr-`). Il est durable et n’a pas de jeton de rafraîchissement : rien à faire tourner, les clients réutilisent simplement le bearer jusqu’à sa révocation. | Jeton | Durée | Remarques | | - | - | - | | Jeton d’accès OAuth ou jeton personnel actuel (`qw-usr-`) | Pas d’expiration fixe | Révocable à tout moment depuis **Gestion de l’équipe > Serveur MCP** ; autorisez à nouveau pour en obtenir un autre | | Ancien jeton d’accès OAuth (`qw-mcp-`) | 1 heure | Anciennes connexions déjà émises uniquement | | Ancien jeton de rafraîchissement tournant (`qw-mcpr-`) | 30 jours | Anciennes connexions déjà émises uniquement ; chaque rafraîchissement renouvelle le jeton | | Code d’autorisation | 5 minutes | Usage unique, protégé par PKCE | Les nouvelles connexions OAuth émettent un jeton `qw-usr-` durable, sans jeton de rafraîchissement. Déconnecter puis reconnecter une ancienne connexion la fait passer à ce flux actuel. ## Jetons d’accès personnels Pour les clients headless qui ne peuvent pas mener un flux OAuth interactif (plateformes d’automatisation comme n8n ou Make, scripts, agents sur mesure), Qwairy propose des **jetons d’accès personnels rattachés à l’utilisateur**. Créez-les et révoquez-les depuis **Gestion de l’équipe > Serveur MCP** dans Qwairy. * Un jeton personnel commence par `qw-usr-` et est lié à **votre compte utilisateur**, pas à une seule équipe. * Il peut lire chaque équipe éligible au MCP à laquelle vous avez accès directement ou par héritage depuis une équipe parente : un seul jeton peut donc couvrir plusieurs workspaces. * Transmettez-le comme jeton bearer : `Authorization: Bearer qw-usr-...`. * Comme le jeton d’accès OAuth, un jeton personnel n’a pas d’expiration fixe. Révoquez-le depuis **Gestion de l’équipe > Serveur MCP** quand vous n’en avez plus besoin. Les jetons personnels sont en lecture seule, comme tout accès MCP à Qwairy : ils n’exposent jamais d’opération d’écriture. ### Choisir une équipe Les outils liés à une marque prennent un `brandId`, et Qwairy rattache cette marque à une seule équipe propriétaire pour l’appel. Une réponse n’agrège jamais les données de marques de plusieurs équipes. Appelez d’abord `list_brands`, puis passez le `brandId` voulu. Les jetons rattachés à l’utilisateur peuvent couvrir les équipes accessibles directement et les sous-équipes héritées via un rôle Propriétaire ou Manager sur une équipe parente. `list_pitch_audits` est l’autre outil de découverte multi-workspaces : il ne liste que les workspaces agence accessibles au jeton et accepte un filtre `teamId` facultatif. Les appels de détail résolvent toujours un seul audit dans un seul workspace autorisé. ## Prise en charge de PKCE Le serveur exige PKCE avec la seule méthode **S256** : * **S256** : hachage SHA-256 du code verifier La méthode `plain` n’est pas prise en charge. La plupart des clients MCP utilisent S256 par défaut, aucune configuration supplémentaire n’est donc nécessaire. ## Sécurité Votre mot de passe Qwairy n’est jamais transmis à un client IA. L’authentification se fait directement auprès du serveur d’authentification de Qwairy. Les jetons sont limités à des types de données précis. Un client MCP n’accède qu’à ce que vous avez autorisé. Les connexions OAuth comme les jetons d’accès personnels sont rattachés à l’utilisateur (`qw-usr-`) : ils couvrent les équipes éligibles au MCP auxquelles vous avez accès directement ou par héritage d’un rôle Propriétaire ou Manager sur l’équipe parente. Chaque appel lié à une marque rattache toutefois le `brandId` demandé à une seule équipe propriétaire, si bien qu’une réponse ne mélange jamais les données de marques de plusieurs équipes. Le code d’autorisation est à usage unique et expire au bout de 5 minutes : la fenêtre pour l’échanger contre un jeton est donc étroite. Le jeton d’accès émis reste révocable à tout moment (voir ci-dessous). Vous pouvez révoquer l’accès à tout moment depuis **Gestion de l’équipe > Serveur MCP** dans Qwairy. ## Échange manuel du jeton Si vous développez votre propre client MCP, enregistrez d’abord le client public, puis réutilisez le `client_id` renvoyé tout au long de l’échange du code d’autorisation. ### 1. Enregistrer le client L’URI de redirection enregistrée ici doit être identique dans les deux requêtes suivantes. ```bash theme={null} curl --request POST https://auth.qwairy.co/register \ --header 'Content-Type: application/json' \ --data '{ "client_name": "My Qwairy MCP client", "redirect_uris": ["http://127.0.0.1:8765/callback"], "grant_types": ["authorization_code"], "response_types": ["code"] }' ``` La réponse contient l’identifiant du client public enregistré : ```json theme={null} { "client_id": "mcp-client-0123456789abcdef0123456789abcdef", "client_name": "My Qwairy MCP client", "redirect_uris": ["http://127.0.0.1:8765/callback"], "grant_types": ["authorization_code"], "response_types": ["code"], "token_endpoint_auth_method": "none" } ``` ### 2. Lancer l’autorisation Générez un verifier RFC 7636 et son challenge S256, puis ouvrez cette URL dans le navigateur de l’utilisateur. Remplacez `REGISTERED_CLIENT_ID` par le `client_id` renvoyé ci-dessus. ```bash theme={null} GET https://auth.qwairy.co/authorize ?response_type=code &client_id=REGISTERED_CLIENT_ID &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback &scope=read%3Abrands%20read%3Avisibility &state=RANDOM_STATE &code_challenge=BASE64URL_SHA256_OF_VERIFIER &code_challenge_method=S256 ``` Le callback contient `code` et `state`. Vérifiez `state` avant d’échanger le code. ### 3. Échanger le code ```bash theme={null} curl --request POST https://auth.qwairy.co/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=AUTH_CODE_FROM_CALLBACK' \ --data-urlencode 'client_id=REGISTERED_CLIENT_ID' \ --data-urlencode 'redirect_uri=http://127.0.0.1:8765/callback' \ --data-urlencode 'code_verifier=ORIGINAL_CODE_VERIFIER' ``` **Réponse :** ```json theme={null} { "access_token": "qw-usr-abc123...", "token_type": "Bearer", "scope": "read:brands read:visibility" } ``` Le jeton d’accès est un jeton durable rattaché à l’utilisateur (`qw-usr-`). Il n’y a ni `refresh_token` ni `expires_in` : réutilisez le bearer jusqu’à sa révocation. ### 4. Réutiliser ou révoquer Le jeton n’expire pas et n’a pas d’étape de rafraîchissement : réutilisez le bearer pour les requêtes suivantes. Pour le renouveler, révoquez l’ancien puis relancez le flux d’autorisation : ```bash theme={null} POST https://auth.qwairy.co/revoke Content-Type: application/x-www-form-urlencoded token=qw-usr-abc123... ``` ## Dépannage ### « Invalid or expired token » Le jeton a été révoqué : les jetons rattachés à l’utilisateur n’expirent pas d’eux-mêmes. Déconnectez puis reconnectez le serveur pour en autoriser un nouveau. ### « Insufficient scope » L’outil appelé exige un scope qui n’a pas été accordé. Reconnectez le serveur et autorisez tous les scopes demandés. ### « No eligible team » Votre compte n’appartient à aucune équipe disposant d’une offre éligible au MCP (Starter et au-delà), ou l’abonnement a expiré. L’autorisation est refusée tant qu’aucun workspace n’est éligible. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.