---
author: OOMOL
author_url: https://oomol.com/fr/about/
title: Connecter les comptes des utilisateurs finaux avec ProjectConnector
description: Utilisez ProjectConnector dans un backend TypeScript pour connecter
  les comptes des utilisateurs SaaS et exécuter des opérations en leur nom.
lang: fr
canonical_url: https://oomol.com/fr/docs/project-connector/
markdown_url: https://oomol.com/fr/docs/project-connector.md
---

# Connecter les comptes des utilisateurs finaux avec ProjectConnector

Utilisez `ProjectConnector` lorsque chaque utilisateur de votre produit doit connecter son propre compte fournisseur. Votre backend identifie chaque utilisateur avec `externalUserId`, crée des liens d’autorisation, stocke les ID des comptes connectés et exécute les opérations pour cet utilisateur.

Ce parcours utilise une clé API de projet au format `oo_proj_…`. Elle est distincte de la clé personnelle `api_…` utilisée par `Connector`.

## Connecter votre Agent

ProjectConnector fournit les appels au service de connexion. OOMOL gère l’autorisation des fournisseurs, le stockage des identifiants, le renouvellement des tokens et l’exécution des opérations. Votre produit fournit l’authentification des utilisateurs, les associations de comptes et les handlers des outils de l’Agent.

Si votre Agent s’exécute sur le backend, ses handlers peuvent appeler ProjectConnector directement. S’il s’exécute sur l’appareil de l’utilisateur, envoyez les requêtes d’outils au backend authentifié de votre produit. La clé API de projet reste sur ce backend.

La configuration MCP hébergée personnelle/d’équipe utilise les connexions des utilisateurs et équipes OOMOL. Pour les comptes des utilisateurs SaaS, utilisez ProjectConnector ou l’API HTTP SaaS. Un client qui exige MCP nécessite un adaptateur MCP authentifié propre à votre produit sur le backend.

## Préparer le projet

Avant d’écrire le flux runtime, créez ces ressources dans OOMOL Console :

1. Un projet Connector.
2. Une configuration de fournisseur pour chaque service que les utilisateurs peuvent connecter.
3. Une clé API de projet stockée dans le gestionnaire de secrets de votre backend.

Le [guide Connector for SaaS](/fr/docs/connector-saas/) couvre la configuration de Console et les requêtes REST correspondantes.

## Installer et initialiser

```sh
npm install @oomol-lab/connector
```

```ts
import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.OOMOL_PROJECT_API_KEY!,
});
```

## Créer une demande d’autorisation OAuth

Utilisez un ID stable provenant de votre propre base de données utilisateur comme `externalUserId` :

```ts
const request = await project.connect.oauth("user_42", {
  service: "gmail",
  connectionName: "work",
  returnUri: "https://app.example.com/connected",
});

redirectUserTo(request.authorizationUrl);
```

Après l’autorisation par l’utilisateur, attendez que la demande atteigne un état final :

```ts
const connected = await project.waitForConnection(request);

if (connected.status === "connected") {
  saveConnectedAccountId(connected.connectedAccountId);
}
```

`project.connect.oauth` renvoie une demande d’autorisation qui attend l’utilisateur. Ce n’est qu’après une autorisation réussie que `waitForConnection` renvoie un `connectedAccountId` dans le résultat de la demande.

Pour les fournisseurs utilisant une clé API ou des identifiants personnalisés, utilisez `connect.apiKey` ou `connect.customCredential`. Ces méthodes valident les identifiants et renvoient un compte connecté de manière synchrone.

## Exécuter une opération pour un utilisateur

```ts
const result = await project.execute(
  "user_42",
  "gmail.search_threads",
  { query: "is:unread" },
  { connectedAccountId: "ca-1" },
);
```

Transmettez `connectedAccountId` lorsque vous le possédez. Il sélectionne un compte précis et évite de dépendre du dernier compte actif. `connectionName` reste disponible si votre produit utilise des alias stables.

Liez une fois l’utilisateur avec `forUser` lorsque plusieurs opérations appartiennent à la même requête ou au même job :

L’exemple Slack nécessite une connexion existante nommée « work » pour cet utilisateur. Utilisez le nom de connexion enregistré par votre backend pour ce compte Slack. forUser lie uniquement l’utilisateur ; le compte se sélectionne dans les options de execute.

```ts
const user = project.forUser("user_42");
await user.execute(
  "slack.post_message",
  { channel: "#general", text: "shipped" },
  { connectionName: "work" },
);
```

## Exposer une opération comme outil de l’Agent

Ce descripteur indépendant du framework montre le schema et le handler à enregistrer dans votre framework Agent. Avant de le créer, authentifiez la requête, vérifiez que l’utilisateur peut exécuter cette opération et chargez son association de compte Gmail depuis votre base de données. `currentUser.id` est l’external user ID déterminé par le backend ; `storedAccount.connectedAccountId` appartient à cet utilisateur. Ces valeurs ne proviennent pas des arguments du modèle.

```ts
const searchMailTool = {
  name: "search_mail",
  description: "Search the current user's Gmail threads.",
  inputSchema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
    additionalProperties: false,
  },
  execute: async (input: { query: string }) =>
    project.forUser(currentUser.id).execute(
      "gmail.search_threads",
      input,
      { connectedAccountId: storedAccount.connectedAccountId },
    ),
};
```

Validez les arguments avec le schema avant d’appeler le handler. Le modèle ne fournit que la requête de recherche. Commencez par les opérations utiles au produit et filtrez selon les services connectés de l’utilisateur ; le SDK n’enregistre pas automatiquement toutes les opérations comme outils de l’Agent.

## Maintenir des limites de produit explicites

Votre produit authentifie ses propres utilisateurs et contrôle les fournisseurs et les opérations qu’ils peuvent utiliser. Conservez la clé API du projet sur le backend, transmettez un `externalUserId` cohérent et stockez le sélecteur de compte renvoyé avec l’utilisateur correspondant de votre produit.

Consultez la [référence du SDK TypeScript](/fr/docs/connector-sdk/) pour les champs de cycle de vie des demandes d’autorisation et des comptes connectés, les types précis des opérations, les erreurs, les nouvelles tentatives, les options d’attente et l’API `ProjectConnector` complète.