Recupèrer les informations d’une freebox via un api

Si on est l’heureux possesseur d’une freebox Ultra, free a caché un petit outil trés utile sans freebox os. La possibilité de récupérer des informations de la freebox via un api

Nous allons donc faire un petit tuto pour pouvoir exploiter cette api

⚠️Les commandes seront faites sur une machine linux qui a l’avantage d’avoir deja tout les éléments dans le kernel donc pas besoin d’installer quoique ce soit mais les commandes sont bien entendu aussi utilisables sur un terminal windows. Il faudra juste installer curl et python si pas déjà installés sur la machine

1 – Activer l’application sur la freebox

curl -X POST "http://<ip de la freebox>/api/v4/login/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "<id de l'application>",
    "app_name": "<nom de l'application>",
    "app_version": "1.0",
    "device_name": "serveur-tuto"
  }'

Une fois la commande envoyée plusieurs choses se passent

  • On a un affichage sur la freebox

On dois appuyer 2 fois sur le bouton de droite pour valider, lorsque la box remets l’heure c’est que c’est bon

  • On a ce retour sur notre terminal

On note bien le app_token et le track_id

  • Si l’on va sur sa box, dans Paramètres de la freebox puis Gestion des accès et finalement Applications on va retrouver son application marquée « Authentification en cours »

On peux cliquer sur le petit stylo pour mettre les autorisations exactes que l’on a besoin pour notre récupération des informations

Une fois les autorisations correctes, retour sur notre terminal puis on tapes

curl "http://<ip de la freebox>/api/v4/login/authorize/<track_id>" 

On peux vérifier sur la box, dans la gestion des accès, si on a bien les accès

Tout est ok

2 – Génération du session_token

La freebox a tout un système de protections

En gros le app token va permettre de générer un challenge et un password_salt puis à partir de ce challenge et password_salt on dois générer un password puis à partir de ce password on va générer un session_token

Pour simplifier les choses et surtout ne pas se prendre de timeout pendant que l’on génére tout ça on va créer le script python suivant qui nous calculera directement tout ça

nano get_session_token.py
#!/usr/bin/env python3
import hmac
import hashlib
import json
import urllib.request

FREEBOX_IP = "<ip de la freebox>"
BASE_URL = f"http://{FREEBOX_IP}/api/v4"

APP_ID = "<ip de l'application donné à l’étape 1>"
APP_TOKEN = "<app_token renvoyé par la première commande>"

def api_get(path):
    url = f"{BASE_URL}{path}"
    with urllib.request.urlopen(url) as resp:
        return json.loads(resp.read().decode("utf-8"))

def api_post(path, payload):
    url = f"{BASE_URL}{path}"
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=data,
        headers={"Content-Type": "application/json"},
        method="POST"
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode("utf-8"))

def main():
    # 1) Récupérer le challenge
    resp = api_get("/login/")
    if not resp.get("success"):
        raise RuntimeError("Échec récupération challenge")
    challenge = resp["result"]["challenge"]

    # 2) Calculer le password
    h = hmac.new(APP_TOKEN.encode("utf-8"), challenge.encode("utf-8"), hashlib.sha1)
    password = h.hexdigest()

    # 3) Ouvrir une session
    resp = api_post("/login/session/", {
        "app_id": APP_ID,
        "password": password
    })
    if not resp.get("success"):
        raise RuntimeError(f"Échec ouverture session: {resp}")

    session_token = resp["result"]["session_token"]
    print(session_token)

if __name__ == "__main__":
    main()

On pense à changer l’ip de la freebox, l’APP_ID et le APP_TOKEN

on appele ensuite ce script pour avoir le session_token

python3 get_session_token.py

en retour on a l’app_id que l’on a donné au départ et un session_token

3 – Lancer l’api pour récupérer les informations

Dans notre exemple, on va récupérer les infos du système de la box

SESSION_TOKEN="<le session_token>"

curl "http://192.168.1.254/api/v4/system/" \
  -H "X-Fbx-App-Auth: $SESSION_TOKEN" | jq

4 – En plus

Il faut savoir que par mesure de sécurité le session_token n’est pas valable infiniment et au bout d’un moment il ne sera plus valide cela oblige alors à refaire la demande du session_token si l’on dois faire une autre requête à l’api, cela est embêtant notamment dans le cadre d’une automatisation

Pour éviter cela on va faire un script python qui fais directement la demande du session_token et l’envoi directement à la commande curl

Voici un exemple de script python qui prend en entrée l’app_id et l’app_token, génère tout ce qu’il a besoin de générer avec la freebox puis lance la requête

nano freebox_system.py
#!/usr/bin/env python3
import hmac
import hashlib
import json
import urllib.request

FREEBOX_IP = "<ip de la freebox>"
BASE_URL = f"http://{FREEBOX_IP}/api/v4"

APP_ID = "<ip de l'application donné à l’étape 1>"
APP_TOKEN = "<app_token renvoyé par la première commande>"

def api_get(path):
    url = f"{BASE_URL}{path}"
    with urllib.request.urlopen(url) as resp:
        return json.loads(resp.read().decode("utf-8"))

def api_post(path, payload):
    url = f"{BASE_URL}{path}"
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        url,
        data=data,
        headers={"Content-Type": "application/json"},
        method="POST"
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode("utf-8"))

def main():
    # 1) Récupérer le challenge
    resp = api_get("/login/")
    if not resp.get("success"):
        raise RuntimeError("Échec récupération challenge")
    challenge = resp["result"]["challenge"]

    # 2) Calculer le password
    h = hmac.new(APP_TOKEN.encode("utf-8"), challenge.encode("utf-8"), hashlib.sha1)
    password = h.hexdigest()

    # 3) Ouvrir une session
    resp = api_post("/login/session/", {
        "app_id": APP_ID,
        "password": password
    })
    if not resp.get("success"):
        raise RuntimeError(f"Échec ouverture session: {resp}")

    session_token = resp["result"]["session_token"]

    # 4) Appel API : /system/
    req = urllib.request.Request(
        f"{BASE_URL}/system/",
        headers={"X-Fbx-App-Auth": session_token},
        method="GET"
    )
    with urllib.request.urlopen(req) as resp_http:
        data = json.loads(resp_http.read().decode("utf-8"))

    print(json.dumps(data, indent=2, ensure_ascii=False))

if __name__ == "__main__":
    main()

et si on lances ce script python

python3 freebox_system.py

On pourrais même aller plus loin en mettant ce script python dans le systemctl puis l’appeler via une bibliothèque externe mais ce n’est pas le but de ce tuto

5 – Les informations récupérables

Toutes les informations récupérables par l’api et à jour se trouvent sur le site dev de free en cliquant ici