---
title: "Authentification"
description: "Deux accès à l'API Matchai : des clés d'API pour votre compte et Se connecter avec Matchai (OAuth 2.1) pour les applications. Portées, actions finales, énergie."
last_updated: "2026-10-21"
lang: "fr-CA"
status: "coming-soon"
canonical: "https://matchai.co/docs/fr/developers/authentication"
---
# Authentification
> Deux accès à l'API Matchai : des clés d'API pour votre compte et Se connecter avec Matchai (OAuth 2.1) pour les applications. Portées, actions finales, énergie.
**Bientôt disponible. Cette fonctionnalité est documentée avant son lancement pour que vous puissiez planifier votre intégration; elle n’est pas encore offerte.**
Source: https://matchai.co/docs/fr/developers/authentication
Chaque requête à l'API Matchai agit pour **un seul compte Matchai**. Il y a deux façons d'obtenir l'identifiant de connexion qui le prouve, et la bonne dépend du compte avec lequel vous travaillez.
## Deux façons d'accéder [#two-ways-in]
| | Clés d'API | Se connecter avec Matchai |
|---|---|---|
| À utiliser pour | Vos propres scripts et vos propres outils IA, sur votre propre compte | Une application qui sert d'autres professionnels : un créateur de sites Web, un CRM, un assistant IA |
| Qui accorde l'accès | Vous, quand vous créez la clé | Le professionnel, en appuyant sur **Autoriser** |
| Identifiant de connexion | Une clé qui commence par `matchai_` | Un jeton d'accès OAuth 2.1, avec un jeton d'actualisation |
| Portées | Choisies quand vous créez la clé | Demandées par votre application et montrées au professionnel |
| Configuration | Créer une clé dans Matchai | [Créer une application Matchai](https://matchai.co/docs/fr/developers/authentication/create-a-matchai-app), puis exécuter le [flux OAuth](https://matchai.co/docs/fr/developers/authentication/connect-with-matchai) |
| Fin de l'accès | Vous révoquez la clé | Le professionnel appuie sur **Déconnecter** |
Les deux vont dans le même en-tête :
```http title="Request header"
Authorization: Bearer matchai_…
```
Un jeton d'accès OAuth s'envoie de la même façon, à la place de la clé.
Créer une clé pour votre propre compte, choisir ses portées, la renouveler et la révoquer.
Enregistrez l'application à laquelle les professionnels se connecteront.
Le flux OAuth 2.1, la page d'autorisation et un exemple de code complet.
Une clé ou un jeton est lié au compte qui l'a accordé, alors il ne peut jamais lire les inscriptions, les contacts ou les messages d'un autre professionnel. Une application qui sert trois courtiers détient trois connexions, chacune avec ses propres jetons, peu importe comment elle est construite. C'est aussi pourquoi une clé personnelle ne peut pas servir à exploiter un service pour d'autres personnes : servir d'autres professionnels passe par Se connecter avec Matchai, où chacun donne son accord.
## Ce qu'une requête peut faire [#what-a-request-can-do]
Une requête peut faire ce que le titulaire du compte peut faire dans Matchai, selon les mêmes règles et les mêmes permissions, et rien de plus. Deux éléments la restreignent davantage :
- Les **portées** limitent les parties du compte auxquelles l'identifiant de connexion peut toucher.
- Les **actions finales** attendent l'approbation du titulaire du compte, à moins qu'il ait permis à votre application de les exécuter.
`GET /v1/me/connection` ([`getConnection`](https://matchai.co/docs/developers/api-reference/me/getConnection)) indique à votre application comment elle est connectée : l'application, les portées accordées, `auth_type` (`api_key` ou `oauth`), `approval_mode` (`ask_me` ou `allowed`) et si la connexion est en mode test.
## Portées [#scopes]
Chaque opération de la [référence de l'API](https://matchai.co/docs/developers/api-reference) indique les portées dont elle a besoin. Ne demandez que ce que votre application utilise : un professionnel est plus enclin à appuyer sur **Autoriser** quand la liste est courte et que chaque ligne a du sens.
| Portée | Ce qu'elle permet |
|---|---|
| `profile:read` | Lire le profil, la langue, le fuseau horaire et l'état de l'énergie du compte |
| `profile:write` | Modifier le profil du compte |
| `listings:read` | Lire les inscriptions, leurs photos, leurs pièces, leurs documents et leurs traductions |
| `listings:write` | Créer et modifier des inscriptions, leurs photos, leurs pièces et leurs traductions, et les supprimer |
| `listings:publish` | Publier et dépublier des inscriptions |
| `sites:read` | Lire les sites Matchai et les inscriptions qui y figurent |
| `sites:write` | Créer, modifier et publier des sites Matchai, et choisir leurs inscriptions |
| `page:read` | Lire la Page Matchai et ses liens |
| `page:write` | Modifier et publier la Page Matchai, ses liens et ses fichiers |
| `contacts:read` | Lire les contacts et les détails des prospects |
| `contacts:write` | Ajouter, modifier, convertir et supprimer des contacts, et enregistrer les demandes de renseignements reçues par le site Web |
| `messages:read` | Lire les conversations, les messages et les courriels envoyés, marquer des conversations comme lues ou les archiver, et rédiger des brouillons de réponse |
| `messages:send` | Envoyer des messages et des courriels, et commencer des conversations, au nom du titulaire du compte |
| `calendar:read` | Lire les disponibilités et les rendez-vous |
| `calendar:write` | Modifier les disponibilités, réserver et modifier des rendez-vous, et enregistrer des demandes de visite |
| `documents:read` | Lire les documents Matchai Cloud et les liens de dépôt |
| `documents:write` | Téléverser, classer, étiqueter, partager et mettre à la corbeille des documents, et créer des liens de dépôt |
| `teams:read` | Lire les équipes, leurs membres et leurs invitations |
| `teams:write` | Créer et gérer des équipes, et inviter ou retirer des membres |
| `projects:read` | Lire les projets, leurs membres, leurs équipes et leurs inscriptions |
| `projects:write` | Créer et gérer des projets, et inviter ou retirer des membres |
| `notifications:read` | Lire les notifications et les préférences de notification |
| `notifications:write` | Marquer des notifications comme lues et modifier les préférences de notification |
| `saved_listings:read` | Lire les inscriptions que le compte a ajoutées à ses favoris |
| `saved_listings:write` | Ajouter des inscriptions aux favoris et les en retirer |
| `analytics:read` | Lire l'analytique des inscriptions, y compris l'activité de l'IA |
| `webhooks:manage` | Gérer les abonnements aux webhooks et lire les événements |
Quand il manque une portée à un identifiant de connexion, l'appel échoue avec `403` et le code `scope_missing`, et le message nomme la portée. Pour une clé, créez une nouvelle clé qui a la portée et [révoquez l'ancienne](https://matchai.co/docs/fr/developers/authentication/api-keys#rotate-a-key). Pour une connexion OAuth, faites repasser le professionnel par le [flux de connexion](https://matchai.co/docs/fr/developers/authentication/connect-with-matchai) de votre application, pour qu'il puisse accepter la liste plus longue.
Quelques opérations ne demandent aucune portée parce qu'elles ne touchent qu'à ce qui est déjà public, comme la consultation du profil publié d'un professionnel. Elles sont marquées **Free** (gratuit) dans la référence, et une clé ou un jeton y est facultatif.
## Actions finales [#final-actions]
Quatre sortes d'actions sont **finales** : envoyer quelque chose à une autre personne, publier quelque chose pour le public, payer, et supprimer du contenu du compte. L'Assistant Matchai demande toujours avant de faire l'une ou l'autre, et l'API impose la même règle à votre application. Chaque action finale est marquée **Final action** (action finale) dans la référence.
Le titulaire du compte choisit comment votre application les gère, connexion par connexion :
| Réglage | Ce qui se passe quand votre application appelle une action finale |
|---|---|
| **Me demander** (par défaut) | L'appel ne s'exécute pas. Il renvoie `202 Accepted` et attend que le titulaire du compte l'approuve dans Matchai. |
| **Autorisé** | L'appel s'exécute tout de suite et renvoie sa réponse habituelle. |
Tout ce qui n'est pas une action finale s'exécute selon les portées de l'identifiant de connexion, comme la même modification le ferait dans l'application : les lectures, les brouillons et les changements aux propres dossiers du titulaire du compte. Retirer la configuration de votre propre application, comme un abonnement à un webhook, n'est pas non plus une action finale.
**Concevez votre application pour les deux réglages.** Le titulaire du compte peut changer le réglage en tout temps, alors ne présumez jamais de celui que vous aurez.
### Suivre une approbation [#follow-an-approval]
Une action finale sous **Me demander** répond `202` et ne fait encore rien :
```json title="Response (202)"
{
"status": "pending_approval",
"approval_id": "1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
"approval_url": "https://matchai.co/approvals/1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b",
"expires_at": "2026-10-25T13:05:00Z",
"summary": "Send a message to Julien Bouchard"
}
```
**Avisez la personne.** Matchai avise le titulaire du compte, qui approuve ou refuse sur une page qui décrit l'action en mots simples. Affichez `summary` dans votre propre interface et faites un lien vers `approval_url`, pour que la personne puisse répondre de là où elle est.
**Attendez le résultat.** Le webhook `approval.resolved` arrive quand la demande reçoit une réponse, ou quand elle expire. Vous pouvez aussi interroger `GET /v1/approvals/{approval_id}` ([`getApproval`](https://matchai.co/docs/developers/api-reference/approvals/getApproval)). Les webhooks sont le meilleur choix : personne n'a à deviner combien de temps une personne prendra.
**Lisez le résultat.** Quand la demande est `approved`, Matchai a exécuté l'appel **exactement comme vous l'avez envoyé**, et `result` contient le statut et le corps que l'appel a renvoyés. Envoyez le texte exact que la personne a vu. Ne réécrivez jamais un brouillon qu'elle a approuvé.
Une approbation a l'un de cinq statuts :
| Statut | Signification |
|---|---|
| `pending` | En attente du titulaire du compte. Rien ne s'est passé. |
| `approved` | Approuvée, et Matchai a exécuté l'appel. `result` contient le résultat. |
| `declined` | Le titulaire du compte a refusé. Rien ne s'est passé. |
| `expired` | Personne n'a répondu avant `expires_at`. Rien ne s'est passé. |
| `cancelled` | Votre application a retiré la demande avec `POST /v1/approvals/{approval_id}/cancel` ([`cancelApproval`](https://matchai.co/docs/developers/api-reference/approvals/cancelApproval)). |
`GET /v1/approvals` ([`listApprovals`](https://matchai.co/docs/developers/api-reference/approvals/listApprovals)) liste les demandes que votre connexion a faites, et accepte un filtre `status`.
Envoyez un `Idempotency-Key` avec chaque action finale. Si votre requête expire et que vous la répétez avec la même clé, vous recevez la même approbation en attente au lieu d'une deuxième.
Cet exemple publie une inscription et gère les deux réglages :
```js title="publish.mjs"
import { randomUUID } from 'node:crypto';
const response = await fetch(`https://api.matchai.co/v1/listings/${listingId}/publish`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MATCHAI_API_KEY}`,
'Idempotency-Key': randomUUID(),
},
});
if (response.status === 202) {
// Ask me: nothing has happened yet.
const pending = await response.json();
console.log(`Waiting: ${pending.summary}`);
console.log(`The account holder can answer at ${pending.approval_url}`);
} else if (response.ok) {
// Allowed: the listing is published now.
const listing = await response.json();
console.log(`Published at ${listing.url}`);
} else {
const { error } = await response.json();
throw new Error(`${error.code}: ${error.message}`);
}
```
## Limites d'énergie [#energy-limits]
Certaines actions dépensent de l'Énergie Matchai, comme les fonctionnalités d'IA le font dans l'application : rédiger une inscription avec l'IA, retoucher des photos, traduire, rédiger un brouillon avec l'IA, envoyer un courriel, et les messages envoyés par texto. La référence marque chacune d'elles et indique le poids de l'action : légère, modérée, élevée, ou variable.
- **L'API n'affiche jamais l'énergie sous forme de nombre.** `GET /v1/me` renvoie son état : `full`, `comfortable`, `low` ou `empty`.
- **Un appel qui demande plus que ce qui reste ne fait rien.** Il répond `402` avec le code `insufficient_energy`, et rien n'est dépensé.
- **Le titulaire du compte peut fixer une limite d'énergie pour chaque connexion**, pour qu'un script qui s'emballe s'arrête à un plafond qu'il a choisi. Quand votre connexion l'atteint, les appels qui dépensent de l'énergie répondent `402` avec le code `energy_limit_reached`, et `GET /v1/me/connection` indique `energy_limit_reached: true`.
Montrez à la personne le `message` d'un `402` : il dit ce qui s'est passé et quoi faire ensuite. Consultez [Erreurs](https://matchai.co/docs/fr/developers/errors#insufficient_energy).
## Mettre fin à une connexion [#ending-a-connection]
Une connexion prend fin de l'une de trois façons, et chacune arrête tous les identifiants de connexion qui lui appartiennent :
- Le professionnel appuie sur **Déconnecter** sur la page Connecteurs.
- Vous révoquez une [clé d'API](https://matchai.co/docs/fr/developers/authentication/api-keys#revoke-a-key).
- Votre application appelle `DELETE /v1/me/connection` ([`disconnect`](https://matchai.co/docs/developers/api-reference/me/disconnect)). Cet appel met fin à la connexion comme si le professionnel avait appuyé sur **Déconnecter**, et ne supprime rien dans le compte.
Une fois une connexion terminée, ses abonnements aux webhooks sont désactivés et ses requêtes répondent `401`. Traitez cette réponse comme un signal de reconnexion, et non comme une panne.
## Mode test [#test-mode]
Une application connectée seulement au compte de son propre développeur est en **mode test**. Les connexions de test ne sont pas facturées, et les événements qu'elles produisent portent `test_mode: true`. La page [Créer une application Matchai](https://matchai.co/docs/fr/developers/authentication/create-a-matchai-app#test-mode) explique comment cela fonctionne, et qui paie une fois que d'autres professionnels se connectent.
Ce que signifie chaque statut et chaque code, et quoi faire.
Comment les requêtes sont limitées par connexion.
Les portées, les prix et les actions finales de chaque point de terminaison.
## Sitemap
- [Toutes les pages de la documentation Matchai](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/fr/llms.txt)