Authentification OAuth

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

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é

Aucun partage de mot de passe

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.

Accès limité par scopes

Les jetons sont limités à des types de données précis. Un client MCP n’accède qu’à ce que vous avez autorisé.

Isolation des équipes

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.

Code d’autorisation à durée courte

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).

Révocation

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.

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é :

{
  "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.

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

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 :

{
  "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 :

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.

Bien démarrer

Référence des outils

Exemples

Workflows

Fonctionnement

Points de terminaison OAuth

Scopes disponibles

Cycle de vie des jetons

Jetons d’accès personnels

Choisir une équipe

Prise en charge de PKCE

Sécurité

Échange manuel du jeton

1. Enregistrer le client

2. Lancer l’autorisation

3. Échanger le code

4. Réutiliser ou révoquer

Dépannage

« Invalid or expired token »

« Insufficient scope »

« No eligible team »

​Fonctionnement

​Points de terminaison OAuth

​Scopes disponibles

​Cycle de vie des jetons

​Jetons d’accès personnels

​Choisir une équipe

​Prise en charge de PKCE

​Sécurité

​Échange manuel du jeton

​1. Enregistrer le client

​2. Lancer l’autorisation

​3. Échanger le code

​4. Réutiliser ou révoquer

​Dépannage

​« Invalid or expired token »

​« Insufficient scope »

​« No eligible team »

Fonctionnement

Points de terminaison OAuth

Scopes disponibles

Cycle de vie des jetons

Jetons d’accès personnels

Choisir une équipe

Prise en charge de PKCE

Sécurité

Échange manuel du jeton

1. Enregistrer le client

2. Lancer l’autorisation

3. Échanger le code

4. Réutiliser ou révoquer

Dépannage

« Invalid or expired token »

« Insufficient scope »

« No eligible team »