Table Of Contents

Previous topic

Api changes from version 2.0 to 3.0

Next topic

Download

Login

Each application identified with an app_name must gain access to Freebox API before being able to use the api. This procedure can only be initiated from the local network, and the user must have access to the Freebox front panel to grant access to the app.

Once the user authorize the app, the app will be provided with a unique app_token associated with a set of default permissions.

This app_token must be store securely by the app, and will not be exchanged in clear text for the following requests.

Note that the user can revoke the app_token, or edit its permissions afterwards. For instance if the user resets the admin password, app permissions will be reset.

Then the app will need to open a session to get an auth_token. The app will then be authenticated by adding this session_token in HTTP headers of the following requests. The validity of the auth_token is limited in time and the app will have to renew this auth_token once in a while.

Obtaining an app_token

TokenRequest object

Download objects have the following attributes

TokenRequest
app_id string

A unique app_id string

app_name string

A descriptive application name (will be displayed on lcd)

app_version string

app version

device_name string

The name of the device on which the app will be used

Request authorization

This is the first step, the app will ask for an app_token using the following call. A message will be displayed on the Freebox LCD asking the user to grant/deny access to the requesting app.

Once the app has obtained a valid app_token, it will not have to do this procedure again unless the user revokes the app_token.

POST /api/v3/login/authorize/

Example request:

POST /api/v3/login/authorize/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "app_id": "fr.freebox.testapp",
   "app_name": "Test App",
   "app_version": "0.0.7",
   "device_name": "Pc de Xavier"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "success": true,
   "result": {
      "app_token": "dyNYgfK0Ya6FWGqq83sBHa7TwzWo+pg4fDFUJHShcjVYzTfaRrZzm93p7OTAfH/0",
      "track_id": 42
   }
}

Track authorization progress

Once the authorization request has been made, the app should monitor the token status by using the following API and using the track_id returned by the previous call.

The status can have one of the following values:

Status Description
unknown the app_token is invalid or has been revoked
pending the user has not confirmed the authorization request yet
timeout the user did not confirmed the authorization within the given time
granted the app_token is valid and can be used to open a session
denied the user denied the authorization request

The app should monitor the status until it is different from pending.

GET /api/v3/login/authorize/{track_id}

Example request:

GET /api/v3/login/authorize/42 HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "status": "pending",
        "challenge": "Bj6xMqoe+DCHD44KqBljJ579seOXNWr2"
    }
}

Example response once the user has validated the request:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "status": "granted",
        "challenge": "Bj6xMqoe+DCHD44KqBljJ579seOXNWr2"
    }
}

Obtaining a session_token

To protect the app_token secret, it will never be used directly to authenticate the application, instead the API will provide a challenge the app will combine to its app_token to open a session and get a session_token

The app will then have to include the session_token in the HTTP headers of the following requests

SessionStart object

Download objects have the following attributes:

SessionStart
app_id string

Same app_id used in TokenRequest to get the app_token

app_version string

app version

password string

The password computed using the challenge and the app_token

To compute the password you have to compute the hmac-sha1 of the challenge and the app_token

password = hmac-sha1(app_token, challenge)

Getting the challenge value

The challenge returned by the API will change frequently and have a limited time validity.

There are several ways of getting the current challenge value, it will always be included in response requesting the app authentication. It is also included in the authorization tracking API response.

You can also explicitly request a challenge with the following API

GET /api/v3/login/

Example request:

GET /api/v3/login/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "success": true,
    "result": {
        "logged_in": false,
        "challenge": "VzhbtpR4r8CLaJle2QgJBEkyd8JPb0zL"
    }
}

Opening a session

Once you have the challenge you just need use the following API to get a session_token

NOTE: in case of session opening failure, ensure that the box you’re connected is the one you expect by checking the uid returned in the answer.

In the response you get your app permissions. App permissions are:

App permission Description
settings Allow modifying the Freebox settings (reading settings is always allowed)
contacts Access to contact list
calls Access to call logs
explorer Access to filesystem
downloader Access to downloader
parental Access to parental control
pvr Access personal video recorder

NOTE: A permission not listed in app permissions is equivalent to having this permission set to false.

POST /api/v3/login/session/

Example request:

POST /api/v3/login/session/ HTTP/1.1
Host: mafreebox.freebox.fr

{
   "app_id": "fr.freebox.testapp",
   "password": "d4da8517c2c25b1b145f2e5ba91bd0589fc0053d"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "success": true,
   "result" : {
         "session_token" : "35JYdQSvkcBYK84IFMU7H86clfhS75OzwlQrKlQN1gBch\/Dd62RGzDpgC7YB9jB2",
         "challenge":"jdGL6CtuJ3Dm7p9nkcIQ8pjB+eLwr4Ya",
         "permissions": {
               "downloader": true,
         }
    }
}

Example response with invalid password:

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
{
    "msg": "Erreur d'authentification de l'application",
    "success": false,
    "uid": "23b86ec8091013d668829fe12791fdab",
    "error_code": "invalid_token",
    "result": {
         "challenge": "DLjXFEf1kaDwAEn6xRUnEVPU++gnjiSn"
    }
}

Closing the current session

to close the current session you can use the following call

POST /api/v3/login/logout/

Example request:

POST /api/v3/login/logout/ HTTP/1.1
Host: mafreebox.freebox.fr

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "success": true,
}

Make an authenticated call to the API

Once you have a valid session_token you should use it by add the the HTTP header X-Fbx-App-Auth

Example request:

GET /api/v3/login/session/ HTTP/1.1
Host: mafreebox.freebox.fr
X-Fbx-App-Auth: 35JYdQSvkcBYK84IFMU7H86clfhS75OzwlQrKlQN1gBch\/Dd62RGzDpgC7YB9jB2

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
   "success": true,
   "result" : {
         [
            ...
         ]
    }
}

Authentication errors

When attempting to access the API, you may encounter the following authentication errors:

NOTE that in this case the HTTP 403 return code will be used as well

Error Description
auth_required Invalid session token, or not session token sent
invalid_token The app token you are trying to use is invalid or has been revoked
pending_token The app token you are trying to use has not been validated by user yet
insufficient_rights Your app permissions does not allow accessing this API
denied_from_external_ip You are trying to get an app_token from a remote IP
invalid_request Your request is invalid
ratelimited Too many auth error have been made from your IP
new_apps_denied New application token request has been disabled
apps_denied API access from apps has been disabled
internal_error Internal error