Welcome

Get started with Firewalla MSP API. (For complete examples, please visit https://github.com/firewalla/msp-api-examples)

Create and manage your personal access token

Go to MSP Settings -> MSP API (1), then click Create New Token (2). Give your token a name (3) and select its permission level (4), which can be either Full Access or Read Only. You may want to create different tokens for different purposes so that you can disable a token if needed without affecting other uses of the token.

Your token will appear. Keep in mind that you can't see this token again, so keep it safe. Copy the token exactly as it appears — it is already in the form your instance needs.

For tokens you have already created, you can modify their names and permissions at any time. Simply click on the token in your token list (5) to rename it or adjust its access rights, then click Save (6). And, very important, you can invalidate a token if you ever think it has been compromised by revoking its access (7). You can always generate more tokens though.

MSP Base URL

There are two kinds of MSP instance. They differ only in the base URL you send requests to; everything after the base — the /v2/... path, the query string, the request body, the response — is identical.

If you sign in at your own domain, you have the first kind. If you sign in at firewalla.net and manage your MSP under /portal, you have the second.

So GET /v2/boxes is one of:

https://mydomain.firewalla.net/v2/boxes
https://firewalla.net/api/v2/boxes

Every example in these docs uses MSP_base_url for this value.

Now let's go through a few examples of what you can do with the Firewalla MSP API.

Examples

List Boxes

The first thing you may want to do is confirm that the boxes you have in your MSP inventory are there. This is also a great place to start using the API as you may need some of the data that you get from this call for other API calls. Let's see what information is available. For the purpose of this guide, we will use curl to make our API calls and jq to format and filter the results because they are available for nearly every platform.

Sample Request - Get list of boxes

// https://github.com/axios/axios
const axios = require("axios");

// Change these variables to what you have
const MSP_base_url = process.env.MSP_base_url || "https://mydomain.firewalla.net";
const token = process.env.token || "your_personal_access_token";

axios({
    method: 'get',
    url: `${MSP_base_url}/v2/boxes`,
    headers: {
        Authorization: `Token ${token}`
    }
}).then(res => {
    console.log(res.data);
})

curl --request GET  \
--url "${MSP_base_url}/v2/boxes" \
--header "Authorization: Token ${your_personal_access_token}"

Sample Response

[
  {
    "gid": "00000000-0000-0000-0000-000000000000",
    "model": "gold",
    "name": "My Firewalla",
    "mode": "router",
    "online": true,
    "version": "1.975",
    "license": "00000000-1111-1111-1111-000000000000",
    "publicIP": "1.1.1.1",
    "location": "Los Angeles, US",
    "lastSeen": 1648632679.193,
    "group": null,
    "deviceCount": 11,
    "ruleCount": 34,
    "alarmCount": 89
  }
]

This site was created to document the Firewalla MSP APIs that are open to the public and make them usable to MSP users. However, since Firewalla MSP is still evolving rapidly, this document might be outdated or incorrect. If you find anything confusing or misleading, you are welcome to tell us in an email to help@firewalla.com.