API — Authentification et jetons OAuth2

La plateforme expose une API HTTP permettant à une application tierce de lire les données de vos projets et de vos locations. Tous les endpoints renvoient du JSON et sont accessibles uniquement en lecture (méthode GET).

Base des endpoints (production) : https://construction.my-smartlife.fr/api/

Tous les endpoints nécessitent une authentification OAuth2. Un appel sans jeton, ou avec un jeton invalide/expiré, renvoie une erreur 401 :

curl https://construction.my-smartlife.fr/api/projects/list

{"detail":"Jeton OAuth manquant"}

Selon votre situation, deux façons d'obtenir un jeton d'accès (access_token) sont disponibles. Les deux produisent un jeton à utiliser de la même manière, dans l'en-tête HTTP :

Authorization: Bearer VOTRE_ACCESS_TOKEN

C'est le flux à utiliser si vous développez une application qui doit accéder à vos propres projets (ou à ceux d'un utilisateur qui vous donne son accord).

1. Enregistrer votre application
Depuis votre profil, onglet « Application OAuth », créez une application : vous obtenez un client_id et un client_secret (affiché une seule fois), ainsi qu'une URL de redirection (redirect_uri) et des portées (scopes) autorisées.

2. Demander l'autorisation de l'utilisateur
Redirigez l'utilisateur vers l'écran de consentement :

GET https://construction.my-smartlife.fr/oauth/authorize.php
  ?client_id=VOTRE_CLIENT_ID
  &redirect_uri=VOTRE_REDIRECT_URI
  &scope=projects:read rentals:read
  &state=une_valeur_aleatoire

Après acceptation, l'utilisateur est redirigé vers votre redirect_uri avec un code temporaire (valable 2 minutes) : ?code=XXXX&state=...

3. Échanger le code contre un jeton

curl -X POST https://construction.my-smartlife.fr/oauth/token.php \
  -d 'grant_type=authorization_code' \
  -d 'code=XXXX' \
  -d 'client_id=VOTRE_CLIENT_ID' \
  -d 'client_secret=VOTRE_CLIENT_SECRET' \
  -d 'redirect_uri=VOTRE_REDIRECT_URI'

Réponse :

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "projects:read rentals:read"
}

4. Renouveler le jeton
Le jeton expire après 1 heure. Utilisez le refresh_token (qui ne change pas de valeur tant qu'il n'est pas utilisé) pour en obtenir un nouveau sans repasser par l'écran de consentement :

curl -X POST https://construction.my-smartlife.fr/oauth/token.php \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=VOTRE_REFRESH_TOKEN' \
  -d 'client_id=VOTRE_CLIENT_ID' \
  -d 'client_secret=VOTRE_CLIENT_SECRET'

Vous pouvez révoquer l'accès à tout moment depuis l'onglet « Application OAuth » du profil : le jeton en cours cesse alors immédiatement de fonctionner.

Ce flux est réservé aux intégrations serveur à serveur pour lesquelles un administrateur Smartlife a créé un client dédié, rattaché à une liste fixe de projets (utile par exemple pour un tableau de bord interne ou un partenaire de confiance).

Un administrateur crée le client :

python app/create_oauth_client.py partenaire-1 \
  --projects 12,18 \
  --scopes project:read,rental:read

Votre application échange ensuite ses identifiants contre un jeton :

curl -u 'partenaire-1:SECRET' -X POST https://construction.my-smartlife.fr/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=project:read rental:read'

Ce flux ne comporte ni écran de consentement ni refresh_token : il suffit de redemander un nouveau jeton avec les mêmes identifiants une fois celui-ci expiré (1 heure).