OAuth2 immobilier : authentification moderne

OAuth2 est le standard d'authentification pour les intégrations entre systèmes. En immobilier, il s'impose dès qu'on dépasse le cas mono-client (intégrateurs, agrégateurs, partenaires). Cet article explique les flux à connaître et leur application concrète.

Pourquoi OAuth2 plutôt qu'une clé API

Une clé API est simple mais a deux limites : pas de scope (la clé peut tout faire), pas d'expiration native (un vol expose toute la base jusqu'à rotation manuelle). OAuth2 résout les deux en émettant des access tokens à durée limitée et à scope restreint.

Les flux OAuth2 pertinents

Flux	Cas d'usage	Quand l'utiliser
Client Credentials	Serveur à serveur	Intégrateur, partenaire
Authorization Code	App avec utilisateur	Apps mobile agence
PKCE	App publique sans secret	Apps mobile, SPA

Flux Client Credentials en détail

Réponse :

Format de réponse

{"access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "properties:read leads:write"}

Obtention d'un access token

curl -X POST 'https://api.ts-immo.org/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=cid_a1b2c3' \
  -d 'client_secret=cs_d4e5f6...' \
  -d 'scope=properties:read leads:write'

Les scopes Ts-Immo

properties:read — lecture des biens.
properties:write — création et modification (réservé partenaires CRM).
medias:read — lecture des photos et médias.
leads:read — lecture des leads remontés.
leads:write — envoi de leads vers le CRM.
webhooks:manage — configuration des webhooks.

Rotation et sécurité

Les client_secret peuvent être rotés à tout moment depuis app.ts-immo.org. Une période de double validité de 7 jours permet la rotation sans interruption. Les access tokens expirent toutes les heures par défaut et ne peuvent pas être étendus indéfiniment.

Stockage et bonnes pratiques

Ne jamais commiter un client_secret dans Git.
Stocker les secrets dans un coffre (Vault, AWS Secrets Manager, Doppler).
Régénérer les access tokens proactivement avant expiration.
Surveiller les logs d'accès dans le dashboard Ts-Immo.

Quand préférer la clé API simple

Pour un usage mono-client (votre propre site web), une clé API Bearer suffit largement. OAuth2 prend tout son sens quand vous distribuez l'accès à plusieurs intégrateurs ou que vous bâtissez une marketplace d'apps.

Questions fréquentes

OAuth2 est-il obligatoire pour utiliser Ts-Immo ?+

Non. La clé API Bearer reste l'option par défaut, parfaitement adaptée à 95 % des cas. OAuth2 est disponible pour les intégrateurs, les partenaires CRM et les apps multi-clients qui ont besoin de scopes fins ou d'access tokens à durée limitée.

Quelle est la durée de vie d'un access token ?+

Par défaut une heure, configurable jusqu'à 24 heures sur demande. Pour les flux interactifs, un refresh_token permet de prolonger sans réauthentifier l'utilisateur. Ts-Immo journalise tous les access tokens émis pour traçabilité.

Que faire si un client_secret fuite ?+

Rotez-le immédiatement depuis le dashboard. La rotation invalide l'ancien secret après 7 jours de double validité. Les access tokens émis avec l'ancien secret restent valides jusqu'à leur expiration naturelle, soit au maximum une heure. Vérifiez ensuite les logs d'accès pour détecter une utilisation suspecte.