Organization

An organization usually represents a customer - which has inventories, licenses. An Organization can contain multiple sites. A site usually represents a deployment at the same location (a campus, an office).

Sites

Create a Site under the Org

POST /api/v1/orgs/:org_id/sites

Example

{
    "name": "Mist Office",
    "timezone": "America/Los_Angeles",
    "country_code": "US",
    "rftemplate_id": "bb8a9017-1e36-5d6c-6f2b-551abe8a76a2",
    "secpolicy_id": "3bcd0beb-5d0a-4cbd-92c1-14aea91e98ef",
    "alarmtemplate_id": "684dfc5c-fe77-2290-eb1d-ef3d677fe168",
    "networktemplate_id": "12ae9bd2-e0ab-107b-72e8-a7a005565ec2",
    "gatewaytemplate_id": "6f9b2e75-9b2f-b5ae-81e3-e14c76f1a90f",
    "aptemplate_id": "16bdf952-ade2-4491-80b0-85ce506c760b",
    "sitetemplate_id": "155fb365-05c6-4d54-925f-1ac14244a95e",

    "latlng": { "lat": 37.295833, "lng": -122.032946 },
    "sitegroup_ids": [ "581328b6-e382-f54e-c9dc-999983183a34", "f57096b9-0c2f-4df6-c77b-ae6ae87a3d43" ],
    "address": "1601 S. Deanza Blvd., Cupertino, CA, 95014"
}

Parameters

Response

{
    "id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "name": "Mist Office",
    "timezone": "America/Los_Angeles",
    "country_code": "US",
    "latlng": { "lat": 37.295833, "lng": -122.032946 },
    "sitegroup_ids": [ "581328b6-e382-f54e-c9dc-999983183a34", "f57096b9-0c2f-4df6-c77b-ae6ae87a3d43" ],
    "address": "1601 S. Deanza Blvd., Cupertino, CA, 95014"
}

Country Codes

Get a list of country codes that we support

GET /api/v1/const/countries

Parameters

Response

[
    {
        "alpha2": "US",
        "numeric": 840,
        "name": "United States",
        "certified": true
    },
    {
        "alpha2": "JP",
        "name": "Japan",
        "numeric": 392,
        "certified": true
    },
    {
        "alpha2": "BY",
        "name": "Belarus",
        "numeric": 112,
        "certified": true,
        "disabled": true
    },
    ...
]

State Codes

Get ISO states based on country code

GET /api/v1/const/states?country_code=US

Parameters

Response

[
    {
        "iso_code": "AK", 
        "name": Alaska"
    },
    {
       "iso_code": "AL",
       "name": "Alabama"
    },
       "iso_code": "AS",
       "name": "American Samoa"
    },
    {
        "iso_code": "AZ",
        "name": "Arizona"
    },
    {
        "iso_code": "CA",
        "name": "California"
    },
     ...
]

AP Channels

Get a list of country codes that we support

GET /api/v1/const/ap_channels?country_code=US

Parameters

Response

{
    "key": "US",
    "name": "United States"
    "code": 840,
    "band24_enabled": true,
    "band24_channels": {
        "20": [
            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
        ],
        "40": [
            1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
        ]
    },
    "band5_enabled": true,
    "dfs_ok": true,
    "band5_channels": {
        "20": [
            36, 40, 44, 48, 52, 56, 60, 64, 100, 104, 108, 112, 116, 132, 136, 140, 149, 153, 157, 161, 165
        ],
        "40": [
            36, 40, 44, 48, 52, 56, 60, 64, 100, 104, 108, 112, 132, 136, 149, 153, 157, 161
        ],
        "80": [
            36, 40, 44, 48, 52, 56, 60, 64, 100, 104, 108, 112, 132, 136, 149, 153, 157, 161
        ],
        "dfs": [
            52, 56, 60, 64, 100, 104, 108, 112, 116, 132, 136, 140
        ]
    }
}

Get the sites that belongs to an Org

GET /api/v1/orgs/:org_id/sites

Get site

GET /api/v1/sites/:site_id

Get stat along with site

GET /api/v1/sites/:site_id/stats

Response

{
    ...
    "msp_id": "9520c63a-f7b3-670c-0944-727774d5a722",

    "num_clients": 50,
    "num_devices": 8,
}

Definition

Update a Site

PUT /api/v1/sites/:site_id

Delete a Site

DELETE /api/v1/sites/:site_id

Site Groups

Site groups are a group of sites under the same Org. It’s many-to-many mapping to sites

/api/v1/orgs/:org_id/sitegroups

Site Group Schema

{
    "name": "Group1"
}

Inventory

Pagination Notice

To improve performance and reduce response size, please use paginated requests. We strongly recommend specifying pagination parameters when calling these endpoints. Even though a call without pagination parameters will return the full list of device stats, this behavior is temporary. In the future, paginated responses (with default values of limit=100 and page=1) will be enforced.

Query Parameters for Pagination:

• limit: The maximum number of items to return per page (default is 100).
• page: The page number to return (default is 1).

When you include these parameters in your request, the response will also contain the following HTTP headers: - X-Page-Page: The current page number. - X-Page-Limit: The limit per page. - X-Page-Total: The total number of items in the result set.

Get inventory of an org

GET /api/v1/orgs/:org_id/inventory?modified_after=1733522845&limit=100&page=1

Response

Response for device type AP

[
    {
        "mac": "d420b080516d",
        "serial": "A0052190206A2",
        "model": "AP41",
        "sku": "AP41-US",
        "hw_rev": "F11",
        "type": "ap",
        "magic": "XXXXXXXXXXXXXXX",
        "name": "SaltLakeHQ-AP6d",
        "jsi": false,
        "org_id": "9777c1a0-6ef6-11e6-8bbf-02e208b2d34f",
        "site_id": "1505f5d6-5366-4ca2-a9e2-2c6b805e5a47",
        "created_time": 1585754725,
        "modified_time": 1649358858,
        "id": "00000000-0000-0000-1000-d420b080516d",
        "deviceprofile_id": null,
        "connected": true
    }
]

Response for device type Switch

[
    {
        "mac": "8403280bc0a0",
        "serial": "HV3620270051",
        "model": "EX2300-C-12P",
        "sku": "EX2300-C-12P",
        "hw_rev": "C",
        "type": "switch",
        "magic": "XXXXXXXXXXXXXXX",
        "name": "SaltLake-EX2300-C",     // configured
        "hostname": "SaltLake-EX2300-C", // reported
        "jsi": false,
        "org_id": "9777c1a0-6ef6-11e6-8bbf-02e208b2d34f",
        "site_id": "1505f5d6-5366-4ca2-a9e2-2c6b805e5a47",
        "created_time": 1623086870,
        "modified_time": 1656353525,
        "id": "00000000-0000-0000-1000-8403280bc0a0",
        "deviceprofile_id": null,
        "connected": true
    }
]

Response for device type Gateway

[
    {
        "mac": "fc334262af00",
        "serial": "CW1419AN0651",
        "model": "SRX320",
        "sku": "SRX320-SYS-JB",
        "hw_rev": "C",
        "type": "gateway",
        "magic": "XXXXXXXXXXXXXXX",
        "name": "LD_SRX",      // configured
        "hostname": "LD_SRX",  // reported
        "jsi": false,
        "org_id": "9777c1a0-6ef6-11e6-8bbf-02e208b2d34f",
        "site_id": "978c48e6-6ef6-11e6-8bbf-02e208b2d34f",
        "created_time": 1616108044,
        "modified_time": 1616108293,
        "id": "00000000-0000-0000-1000-fc334262af00",
        "adopted": true,
        "deviceprofile_id": null,
        "connected": true
    }
]

Response Definitions

Get filtered inventory of an org

GET /api/v1/orgs/:org_id/inventory?model=AP41

Supported filters: model, serial, magic, site_id, type, mac, vc_mac, vc, unassigned

Org Inventory Search

GET /api/v1/orgs/:org_id/inventory/search?mac=f01c2df166e0

Request

The following fields are available for searching.

Response

{
    "results": [
        {
            "type": "switch",
            "name": "mist-wa-ex4300-VC",
            "mac": "f01c2df166e0",
            "vc_mac": "f01c2df166e0",
            "model": "EX4300-48P",
            "master": true
            "site_id": "01dc141d-b6af-4baa-b00f-0e31ef954c4f",
            "org_id": "9b853544-51e4-45fb-81ac-a442e4a111d0",
            "serial": "PD3714460200",
            "members": [
                {
                    "mac": "f01c2df166e0",
                    "model": "EX4300-48P",
                    "serial": "PD3714460200"
                }
            ],
            "sku": "EX4300-48P",
            "version": "21.4R3.5",
            "status": "disconnected"
        }
    ]
    "limit": 1000,
    "total": 1
}

Count by Distinct Attributes of Inventory

GET /api/v1/orgs/:org_id/inventory/count?type=switch&distinct=model

Request

Response

{
    "limit": 10,
    "distinct": "model",

    "total": 2,
    "results": [
        {
            "model": "EX4300-48P",
            "count": 12
        },
        {
            "model": "EX4400-24P",
            "count": 4
        }
    ]
}

VC (Virtual-Chassis) Management

Ideally VC should be managed as a single device - where

• one managed entity where config / monitoring is anchored against (with a stable identify MAC)
• all members appears in the inventory

In our implementation, we strive to achieve that without manual user configurations by

1. during claim or adoption a VC, we require FPC0 to exist and will use its MAC as identify for the entire chassis
2. other VC members will be automatically populated when they’re all present

The perceivable result is

1. from /sites/:site_id/stats/devices/:fpc0_mac API, you’d see the VC where module_stat contains the VC members
2. from /orgs/:org_id/inventory?vc=true API, you’d see all VC members with vc_mac pointing to the FPC0

Add inventory to an org

POST /api/v1/orgs/:org_id/inventory

Request

[
    "6JG8E-PTFV2-A9Z2N",
    "DVH4V-SNMSZ-PDXBR"
]

Parameters

a list of claim codes

Response if any of entries are valid or there’s no errors

Status: 200 OK

{
    "added": [ "6JG8E-PTFV2-A9Z2N" ],
    "duplicated": [ "DVH4V-SNMSZ-PDXBR" ],
    "error": [ "PO1025335ohoh" ],
    "inventory_added": [
        {
            "serial": "FXLH2015150025",
            "model": "AP41",
            "type": "ap",
            "magic": "6JG8EPTFV2A9Z2N",
            "mac": "5c5b35000018"
        }
    ],
    "inventory_duplicated": [
        {
            "serial": "FXLH2015150027",
            "model": "AP41",
            "type": "ap",
            "magic": "DVH4VSNMSZPDXBR",
            "mac": "5c5b35000012"
        }
    ]
}

Response if none of the entries are valid

Status: 400 Bad Request

Add inventory to an org while limiting device type

POST /api/v1/orgs/:org_id/inventory/switch

Request

[
    "6JG8E-PTFV2-A9Z2N",
    "DVH4V-SNMSZ-PDXBR"
]

Delete multiple inventory from org

This removes the inventory from the org. If the inventory is already assigned to a site, it will be unassigned.

PUT /api/v1/orgs/:org_id/inventory

Request

{
    "op": "delete",
    "serials": [
        "FXLH2015150025",
        "FXLH2015150026"
    ],
    "macs": [
        "5c5b350e0001"
    ]
}

Parameters

Response

{
    "op": "delete",
    "success": [ "FXLH2015150025", "5c5b350e0001" ],
    "error": [ "FXLH2015150026" ]
}

Assign inventory to a site

PUT /api/v1/orgs/:org_id/inventory

Request

{
    "op": "assign",
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "macs": [
        "5c5b350e0001"
    ],
    "no_reassign": false,

    // for cloud-ready switches/gateways
    "disable_auto_config": false

    // for adopted switches
    "managed": false
}

Parameters

Response

{
    "op": "assign",
    "success": [ "5c5b350e0001" ]
    "error": [ ]
}

Unassign inventory from any site

PUT /api/v1/orgs/:org_id/inventory

Request

{
    "op": "unassign",
    "macs": [
        "5c5b350e0001"
    ]
}

Parameters

Response

{
    "op": "unassign",
    "success": [ "5c5b350e0001" ]
    "error": [ ]
}

Create HA Cluster from unassigned Gateways

POST /api/v1/orgs/:org_id/inventory/create_ha_cluster

{
    "nodes": [
        {
            "mac": "aff827549235"  // node0 mac, should be unassigned
        },
        {
            "mac": "8396cd006c8c"  // node1 mac, should be unassigned
        }
    ],

    // optional
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "managed": false,            // if the device is adopted
    "disable_auto_config": true  // if the device is manufed
}

Delete HA Cluster

POST /api/v1/orgs/:org_id/inventory/delete_ha_cluster

{
    "mac": "aff827549235"  // node0 mac
}

After HA cluster deleted, both of the nodes will be unassigned.

Get Org Devices Summary

GET /api/v1/orgs/:org_id/devices/summary

Response

{
    "num_aps": 630,
    "num_switches": 30,
    "num_gateways": 6,
    "num_unassigned_aps": 5,
    "num_unassigned_switches": 0,
    "num_unassigned_gateways": 0,
    "num_mxedges": 1
}

Get Org Devices Stats

This API renders some high-level device stats, pagination is assumed and returned in response header (as the response is an array)

GET /api/v1/orgs/:org_id/stats/devices?limit=100

Request Filters

Response

X-Page-Limit: 100
X-Page-Page: 1
X-Page-Total: 31

[
    {
        "mac": "5c5b35000010",
        "model": "AP200",
        "type": "ap",
        "serial": "FXLH2015170017",
        "last_seen": 1470417522,
        "name": "conference room",
        "status": "connected",
        "version": "1.0.0",
        "ip": "10.2.9.159", // first IP
        "uptime": 13500
    },
    ...
]

Custom Roles

Custom roles restrict Org users to specific UI views. This is useful for limiting UI access of Org users.

You can invite a new user or update existing users in your Org to this custom role. For this, specify view along with role when assigning privileges.

Below are the list of supported UI views. Note that this is UI only feature

Admins

Get Admins

Get a list of people who can manage the Site/Org under the Org

GET /api/v1/orgs/:org_id/admins

Response

[
    {
        "admin_id": "456b7016-a916-a4b1-78dd-72b947c152b7",
        "first_name": "Joe",
        "last_name": "Smith",
        "two_factor_verified": false,
        "privileges": [
            { "scope":"org", "role": "admin" },
            { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin" },
            { "scope":"sitegroup", "sitegroup_id": "581328b6-e382-f54e-c9dc-999983183a34", "role": "admin" }
        ]
    },
    {
      "admin_id": "72bfa2bd-e58a-4670-9d20-a1468f7a6f58",
      "first_name": "John",
      "last_name": "Doe",
      "two_factor_verified": true,
      "privileges": [
         { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "write", "view": "location" },
         { "scope":"site", "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b", "role": "write", "view": "location" }
      ]
    },
    {
        "invite_id": "456b7016-a916-a4b1-78dd-72b947c152b7",
        "email": "joe@abc.com",
        "first_name": "Joe",
        "last_name": "Smith",
        "privileges": [
            { "scope":"org", "role": "admin" },
            { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin" }
        ],
        "expire_time": 1445966955
    },
    {
        "invite_id": "15899c53-92da-4119-bdcf-65203bc84663",
        "email": "jsnow@abc.com",
        "first_name": "John",
        "last_name": "Snow",
        "privileges": [
            { "scope":"org", "role": "read", "view": "reporting" }
        ],
        "expire_time": 1445966955
    }
]

Response Definition

Update Admins

Update admin privileges under the Org

PUT /api/v1/orgs/:org_id/admins/:admin_id

Request

{
    "privileges": [
        { "scope":"org", "role": "write", "view": "reporting" },
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "write", "view": "reporting" },
        { "scope":"sitegroup", "sitegroup_id": "581328b6-e382-f54e-c9dc-999983183a34", "role": "write", "view": "reporting" }
    ]
}

Response

Status: 200 OK

Revoke Admin

This removes all privileges this admin has against the org

DELETE /api/v1/orgs/:org_id/admins/:admin_id

Response

Status: 200 OK

Invite Admin

An Org admin can invite other admin to manage (admin or read) the Org and/or Site(s) under the Org.

POST /api/v1/orgs/:org_id/invites

Request

{
    "email": "joe@abc.com",
    "first_name": "Joe",
    "last_name": "Smith",
    "hours": 24,
    "privileges": [
        { "scope":"org", "role": "admin", "view": "location" },
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin", "view": "location" }
    ]
}

Parameters

Response

Status: 200 OK

An email will also be sent to the user with a link to https://manage.mist.com/verify/invite?token=:token&expire=1459632743&org=OrgName

Verify Invitation

POST /api/v1/invite/verify/:token

Response if successful

Status: 200 OK

NOTE: another call to GET /api/v1/self is required to see the new set of privileges

Response if secret is invalid or verification expired

Status: 404 Not Found

{
    "detail": "invalid secret"
}

Response if the invitation is claimed by the same one requesting it

Status: 404 Not Found

{
    "detail": "invite created by self"
}

Un-invite Admin

DELETE /api/v1/orgs/:org_id/invites/:invite_id

Update the Invite

PUT /api/v1/orgs/:org_id/invites/:invite_id

Request

{
    "hours": 24,
    "privileges": {
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "write", "view": "reporting" },
        { "scope":"sitegroup", "sitegroup_id": "581328b6-e382-f54e-c9dc-999983183a34", "role": "write", "view": "reporting" }
    }
}

API Token

API tokens can be generated for a specific Org/Site with the required privileges

Create API Token

Note that the token key is only available during creation time.

POST /api/v1/orgs/:org_id/apitokens

Request

{
    "name": "org_token_xyz",
    "privileges": [
        { "scope":"org", "role": "read" },
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin" },
        { "scope":"sitegroup", "sitegroup_id": "581328b6-e382-f54e-c9dc-999983183a34", "role": "write" }
    ],
    "src_ips": ["63.3.56.0/24", "63.3.55.4"]
}

Parameters

Response

{
    "name": "org_token_xyz",
    "id": "7cc917df-630a-1508-1889-e18028052dde",
    "key": "MEaTAllON7hM0GUquvka2czM0xE9RIh2bpkZK2UqefoHoT1bDzET7FcXB9POI8o9zkkMy52doYpz3gG4aiDpStZOv4zQ3quf",
    "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
    "src_ips": ["63.3.56.0/24", "63.3.55.4"]
}

Use API Token

To use API token, add a Authorization header when making an API request like the following:

Authorization: Token <key>

GET /api/v1/self

List Current API Tokens

GET /api/v1/orgs/:org_id/apitokens

Response

[
    {
        "name": "org_token_xyz",
        "id": "7cc917df-630a-1508-1889-e18028052dde",
        "key": "MEaT...3quf",
        "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
        "created_by": "joe@abc.com",
        "privileges": [
            {
                "scope": "org",
                "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
                "role": "write"
            }
        ],
        "src_ips": ["63.3.56.0/24", "63.3.55.4"]
    },
    {
        "name": "?",
        "id": "864f351a-1377-4ad9-83f8-72f3fe6199ba",
        "key": "1qkb...QQCL",
        "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
        "created_by": null,
        "privileges": [
            {
                "scope": "site",
                "site_id": "d96e3952-53e8-4266-959a-45acd55f5114",
                "role": "admin"
            }
        ]
    }
]

Response Definition

Update API Token

PUT /api/v1/orgs/:org_id/apitokens/:apitoken_id

Request

{
    "name": "org_token_pqr",
    "privileges": [
        { "scope":"org", "role": "write" },
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin" }
    ],
    "src_ips": ["63.3.56.0/24", "63.3.55.6"]
}

Parameters

Response

Status: 200 OK

Get API Token

GET /api/v1/orgs/:org_id/apitokens/:apitoken_id

Response

[
    {
        "name": "org_token_pqr",
        "id": "7cc917df-630a-1508-1889-e18028052dde",
        "key": "MEaT...3quf",
        "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
        "created_by": "joe@abc.com"
        "privileges": [
            {
                "scope": "org",
                "org_id": "bc411cd9-0d1b-4713-94df-eee8617758ed",
                "role": "write"
            },
            {
                "scope": "site",
                "site_id": "d96e3952-53e8-4266-959a-45acd55f5114",
                "role": "admin"
            }
        ],
        "src_ips": ["63.3.56.0/24", "63.3.55.6"]
    }
]

Delete an API Token

DELETE /api/v1/orgs/:org_id/apitokens/:apitoken_id

Response

Status: 200 OK

SDK Invite

SDK Invites can be generated for (and belongs to) an Org. They can be generated by an Admin of an Org and can be revoked at anytime.

Create a New SDK Invite

POST /api/v1/orgs/:org_id/sdkinvites

Request

{
    "name": "Macy's"
}

Parameters

Response

{
    "id": "5034b980-b49e-501c-66e0-9de4c38f18a2",
    "name": "Macy's",
    "enabled": true,
    "quota": -1,
    "created_time": 1428954000
    "expire_time": 1428954000
}

Delete/Revoke a SDK Invite

DELETE /api/v1/orgs/:org_id/sdkinvites/:sdkinvite_id

Get QRCode for a SDK Invite

GET /api/v1/orgs/:org_id/sdkinvites/:sdkinvite_id/qrcode

Send SDK Invite as Email / SMS

POST /api/v1/orgs/:org_id/sdkinvites/:sdkinvite_id/email
POST /api/v1/orgs/:org_id/sdkinvites/:sdkinvite_id/sms

Request

// when sending email
{
    "email": "test@abc.com"
}

// when sending sms
{
    "number": "14081234567"
}

SDK Client Activation

POST /api/v1/mobile/verify/:secret

Request

{
    "device_id": "b069b358-4c97-5319-1f8c-7c5ca64d6ab1"
}

Response

{
    "name": "Macy's",
    "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
    "secret": "device-specific-secret"
}

SDK Client

Update SdkClient information

PUT /api/v1/orgs/:org_id/sdkclients/:sdkclient_id

Request

{
    "name": "John Smith"
}

SDK Template

SDK Template stores the customization (e.g. background image, text…)

Create a New SDK Template

POST /api/v1/orgs/:org_id/sdktemplates

Request

{
    "name": "default"
    "welcome_msg": "Welcome to Mist",
    "bg_image"   :"http://p.imgci.com/db/PICTURES/CMS/227700/227791.4.jpg",
    "btn_flr_bgcolor" : "#282828",
    "search_txtcolor" : "#282828",
    "header_txt":"Mist",
    "default": true
}

Parameters

Update Sdk Template

PUT /api/v1/orgs/:org_id/sdktemplates/:sdktemplate_id

Delete/Revoke a SDK Template

DELETE /api/v1/orgs/:org_id/sdktemplates/:sdktemplate_id

License

Get License Summary

GET /api/v1/orgs/:org_id/licenses

Response

{
    "licenses": [
        {
            "order_id": "00000464",
            "subscription_id": "SUB-0000144",
            "type": "SUB-MAN",
            "start_time": 1504828800,
            "end_time": 1520380800,
            "quantity": 180
        },
        {
            "order_id": "00000464",
            "subscription_id": "SUB-0000145",
            "type": "SUB-MAN",
            "start_time": 1504828800,
            "end_time": 1520380800,
            "quantity": 30
        }
        {
            "order_id": "00000464",
            "subscription_id": "SUB-0000146",
            "type": "SUB-LOC",
            "start_time": 1504828800,
            "end_time": 1520380800,
            "quantity": 120
        }
    ],
    "amendments": [
        {
            "id": "2b9116ab-cd1e-e897-6e08-31fccd88e792",
            "subscription_id": "SUB-0000144",
            "type": "SUB-MAN",
            "start_time": 1504828800,
            "end_time": 1520380800,
            "quantity": -30
        },
        {
            "id": "4e974f27-fcbc-03cb-caa4-688e20aa539f",
            "subscription_id": "SUB-0000146",
            "type": "SUB-LOC",
            "start_time": 1504828800,
            "end_time": 1520380800,
            "quantity": 75
        },
    ],
    // current usage summary (across sites)
    "summary": {
        "SUB-MAN": 150,
        "SUB-LOC": 120
    },
    "entitled": {
        "SUB-MAN": 180,
        "SUB-LOC": 195
    }
}

Definitions

Get License Usage By Sites

This shows license usage (i.e. needed) based on the features enabled for the site.

GET /api/v1/orgs/:org_id/licenses/usages

Response

[
    {
        "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
        "num_devices": 80,
        "usages": {
            "SUB-MAN": 60
            "SUB-LOC": 30
        },
        "fully_loaded": {
            "SUB-MAN": 80
            "SUB-LOC": 30
        }
    }
]

Definitions

Claim an Order by Activation Code

POST /api/v1/orgs/:org_id/claim

Example

{
    "code": "ZHT3K-H36DT-MG85D-M61AC",
    "type": "all"
}

Parameters

Response of the license(s) that are successfully claimed and applied

{
    "license_added": [
        {
            "type": "SUB-MAN",
            "start": 1504828800,
            "end": 1520380800,
            "quantity": 180
        },
        {
            "type": "SUB-LOC",
            "start": 1504828800,
            "end": 1520380800,
            "quantity": 120
        }
    ],
    "license_duplicated": [
        {
            "type": "SUB-MAN",
            "start": 1504828800,
            "end": 1520380800,
            "quantity": 180
        }
    ],
    "license_error": [
        {
            "order": "00000464",
            "reason": ""
        }
    ],
    "inventory_added": [
        {
            "serial": "FXLH2015150025",
            "model": "AP41",
            "type": "ap",
            "magic": "6JG8EPTFV2A9Z2N",
            "mac": "5c5b35000018"
        }
    ],
    "inventory_duplicated": [
        {
            "serial": "FXLH2015150027",
            "model": "AP41",
            "type": "ap",
            "magic": "DVH4VSNMSZPDXBR",
            "mac": "5c5b35000012"
        }
    ],
    "inventory_pending": [ 
        {
            "mac": "5c5b35000012" // for async claim
        }
    ]
}

Response when the key is invalid (or already used)

Status: 400 Bad Request

Get Processing Status for Async Claim

GET /api/v1/orgs/:org_id/claim/status?detail=False

Response

{
    'status': 'done', //prepared, ongoing, done
    'total': 2, 
    'scheduled_at': 1709598052, 
    'processed': 2, 
    'failed': 0, 
    'succeed': 2, 
    'timestamp': 1709598053, 
    'incompleted': [], 
    'completed': ['000000000022', '000000000011'], 
    'details': [{
        'mac': '000000000022', 
        'status': 'added', 
        'timestamp': 1709598053, 
        }
    ]
}

Response Definition

Move License To Another Org

If the admin has admin privilege against the org_id and dst_org_id, he can move some of the licenses to another Org. Given that:

1. the specified license is currently active
2. there’s enough licenses left in the specified license (by subscription_id)

3. there will still be enough entitled licenses for the type of license after the amendment

   PUT /api/v1/orgs/:org_id/licenses

Request

{
    "op": "amend",
    "subscription_id": "SUB-0000144",
    "dst_org_id": "3eff35f7-c218-894e-bca2-24e5325601cc",
    "quantity": 10
}

Parameters

Undo the License Move

PUT /api/v1/orgs/:org_id/licenses

Request

{
    "op": "unamend",
    "amendment_id": "2b9116ab-cd1e-e897-6e08-31fccd88e792",
}

Delete License

PUT /api/v1/orgs/:org_id/licenses

Request

{
    "op": "delete",
    "subscription_id": "SUB-0000144"
}

Annotate a License

PUT /api/v1/orgs/:org_id/licenses

Request

{
    "op": "annotate",
    "subscription_id": "SUB-000144",
    "notes": "customer notes"
}

Audit Logs

Audit logs records all administrative activities in an Org

Get a list of change logs for the current Org

GET /api/v1/orgs/:org_id/logs?start=1431384000&end=1431298000&limit=100

Supported Filters

Response

The logs are always sorted by time in descending order

{
    "start": 1428939600,
    "end":   1428954000,
    "limit": 100,

    "total": 135,
    "results": [
        {
            "timestamp": 1431382121,
            "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
            "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
            "admin_id": "72bfa2bd-e58a-4670-9d20-a1468f7a6f58",
            "admin_name": "test@mistsys.com",
            "message": "TEST AUDIT",
            "id": "c6f9347b-b0a4-4a23-b927-fa9249f2ffb2"
        }
    ]
}

Count by Distinct Attributes of Audit Logs

GET /api/v1/orgs/:org_id/logs/count?distinct=admin_name

Request

Response

{
    "start": 1511967600,
    "end": 1513177200,
    "limit": 10,
    "distinct": "admin_name",

    "total": 2,
    "results": [
        {
            "admin_name": "John Smith john.smith@corp.com",
            "count": 61
        },
        {
            "admin_name": "Eric Sky eric@corp.com",
            "count": 44
        }
    ]
}

Org

Org admin can invite people to manage the org. Furthermore, he can dictate the level of security those accounts are. The check is enforced when the invited admin tries to “accept” the invitation and every time the admin tries to login

Create Org

POST /api/v1/orgs

Scheme

{
    "name": "ABC Company",
    "session_expiry": 1440,

    "alarmtemplate_id": "684dfc5c-fe77-2290-eb1d-ef3d677fe168",
    "orggroup_ids": [ "507f1bab-13ba-73e2-f291-2bcb8d1362b0" ]
    "allow_mist": true
}

Parameters

Get Org

GET /api/v1/orgs/:org_id

Response

{
    'name': 'Org',
    'id': '2818e386-8dec-2562-9ede-5b8a0fbbdc71',
    'msp_id': 'b9d42c2e-88ee-41f8-b798-f009ce7fe909',
    'created_time': 1652905706,
    'modified_time': 1652905706,
    'allow_mist': True,
    'session_expiry': 1440,
    'alarmtemplate_id': None,
    'msp_name': 'MSP',
    'msp_logo_url': 'https://.../logo/b9d42c2e-88ee-41f8-b798-f009ce7fe909.jpeg'
}

Definitions

Update Org

PUT /api/v1/orgs/:org_id

Delete Org

DELETE /api/v1/orgs/:org_id

Clone Org

Create an Org by cloning from another one. Org Settings, Templates, Device Profiles, Alarm Templates, RFTemplates, Security Policies, Wxlan Tags, Wxlan Tunnels, Wxlan Rules, Org Wlans will be copied. Sites and Site Groups will not be copied, and therefore, the copied template will not be applied to any site/sitegroups.

POST /api/v1/orgs/:org_id/clone

Request

{
    "name": "New Org"
}

Org Stats

GET /api/v1/orgs/:org_id/stats

Response

{
    "num_inventory": 12,
    "num_devices": 10,
    "name": "Sam MSP Customer 5",
    "orggroup_ids": [],
    "allow_mist": false,
    "num_devices_connected": 8,
    "num_devices_disconnected": 2,
    "num_sites": 1,
    "id": "448a3934-df89-11e5-8898-1258369c38a9"
}

Definitions

Org Setting

Get Org Setting

GET /api/v1/orgs/:org_id/setting

Request

{
    "password_policy": {
        "enabled": true
        "expiry_in_days": 60,
        "min_length": 8,
        "requires_special_char": false,
        "requires_two_factor_auth": true
    },
    "ui_idle_timeout": 10,
    "ui_no_tracking": false,  // default is false

    "switch_mgmt": {
         "ap_affinity_threshold": 10
    },

    "mgmt": {
        "use_wxtunnel": false,
        "use_mxtunnel": true,
        "mxtunnel_ids": ["08cd7499-5841-51c8-e663-fb16b6f3b45e"]
    },

    "disable_remote_shell": false,
    "disable_pcap": false,
    "pcap": {
        "bucket": "myorg-pcap"
        "max_pkt_len": 128
    },
    "pcap_bucket_verified": true,

    "security": {
        "disable_local_ssh": false,
        "limit_ssh_access": false,
        "fips_zeroize_password": "NUKETHESITE"
    },

    // controls api behavior
    "api_policy": {
        // by default, API hides password/secrets when the user doesn't have write access
        "no_reveal": true,  // false (default, may change) / true (API will not return any secrets)
    },

    "installer": {
        "grace_period": 14,
        "extra_site_ids": [
            "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
            "52f4347e-3e4b-186c-21ca-ad5b70eb23d6"
        ],
        "allow_all_sites": false,
        "allow_all_devices": false
    },

    "wan_pma": {
        "enabled": false  // default is false
    },
    "wired_pma": {
        "enabled": false  // default is false
    },
    "wireless_pma": {
        "enabled": true  // default is true 
    },

    "auto_site_assignment": {
        "enable": true,

        "rules": [
            // use device name (via Installer APIs)
            {
                "src": "name",
                "expression": "[0:3]",           // "abcdef" -> "abc"
                              "split(.)[1]",     // "a.b.c" -> "b"
                              "split(-)[1][0:3], // "a1234-b5678-c90" -> "b56"
                "prefix": "XX-",
                "suffix": "-YY"
            },
            // use ext_ip
            {
                "src": "ext_ip",
                "subnet": "34.82.100.0/24",
                "value": "site1"
            },
            // use subnet
            {
                "src": "subnet",
                "subnet": "10.1.2.0/18",
                "value": "s1351"
            },
            // use LLDP System Name
            {
                "src": "lldp_system_name",
                "expression": "..." // same as above
            },
            // use DNS Suffix
            {
                "src": "dns_suffix",
                "expression": "..." // same as above
            },
            {
                "src": "model",
                "model": "AP41",
                "value": "s1351"
            },
            {
                // optional filters
                "match_device_type": "ap",  // ap / switch / gateway / other, default is `ap`
                "match_model": "AP41",

                ...
            },
            {
                // DRAFT
                "match_device_type": "gateway",
                "src": "geoip",
                "match_country": ...

                // site name for the device to be assigned to
                "value": "city",  // "city" / "city+country" / ...

                // by default, a claimed device only gets assigned if the site exists
                // to auto-create the site, enable this
                "create_new_site_if_needed": true,
                // and if a gateway template is desired for this newly created site
                "gatewaytemplate_id": "6f9b2e75-9b2f-b5ae-81e3-e14c76f1a90f"                
            },            
        ]
    },

    "auto_device_naming": {
        "enable": true,

        "rules": [
            {
                // use LLDP Port Description
                "src": "lldp_port_desc",
                "prefix": "MIST-",
                "suffix": ""
                "expression": "..." // same as above
            },
            {
                // use mac directly
                "src": "mac",
                "prefix": "MIST-",
                "suffix": "",
                "match_device_type": "ap",  // ap / switch / gateway, default is `ap`
            }
        ]
    },

    "cloudshark": {
        "apitoken": "accbd6f10c6d05c3"

        // if using CS Enteprise
        "url": "https://cloudshark.hosted.domain"
    }

    "cradlepoint": {
        "ecm_api_id": "73446d61-2206-4ea5-855a-0043f980be62",
        "ecm_api_key": "68b329da9893e34099c7d8ad5cb9c9405",
        "cp_api_id": "84446d61-2206-4ea5-855a-0043f980be54",
        "cp_api_key": "79c329da9893e34099c7d8ad5cb9c941",
    },

    "celona": {
        "api_prefix": "cc3273fcb016470e",
        "api_key": "$2a$04$OkaLCoJn6rDjR8ha.oduQVDST3.kJNIrte"
    },

    "auto_deviceprofile_assignment": {
        "enable": true,

        "rules": [
            // same rules definition that can be used for auto_site_assignment
        ]
    },


    // RADSec certs for AP
    "cacerts": [
        "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
        "-----BEGIN CERTIFICATE-----\nBhMCRVMxFDASBgNVBAoMC1N0YXJ0Q29tIENBMSwwKgYDVn-----END CERTIFICATE-----"
    ],
    "device_cert": {
        "cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
        "key": "-----BEGIN PRI..."
    },

    "tags": [ "beta" ],
    "device_updown_threshold": 0,
    // by default, device_updown_thresold, if set, will apply to all devices types
    // if different values for specific device type is desired, use the following
    "ap_updown_threshold": null,
    "gateway_updown_threshold": 10,
    "switch_updown_threshold": 0,

    "mxedge_mgmt": {
        "mist_password": "MIST_PASSWORD",
        "root_password": "ROOT_PASSWORD",
        "fips_enabled": true, // default is false
        "oob_ip_type": "disabled",  // dhcp (default) / disabled
        "oob_ip_type6": "disabled", // autoconf (default) / dhcp / disabled
        "config_auto_revert": true, // default is false
    },

    "blacklist_url": "https://papi.s3.amazonaws.com/blacklist/xxx...",

    "mist_nac": {
        // default is false. By default NAC POD failover considers all NAC pods available around the globe,
        // i.e. EU, US, or APAC based, failover happens based on geo IP of the originating site.
        // For strict GDPR compliancy NAC POD failover would only happen between the PODs located within the EU environment,
        // and no authentication would take place outside of EU. This is an org setting that is applicable
        // to WLANs, switch templates, mxedge clusters that have mist_nac enabled
        "eu_only": false,

        // by default NAS devices(switches/aps) and proxies(mxedge) are configured to use port 2083(radsec) to reach mist-nac
        // to override that port with 443(ssl), use the following knob
        // this is a org level setting that is applicable to wlans, switch-templates, and mxedge-clusters that have
        // mist-nac enabled
        "use_ssl_port": true,

        // by default NAS devices(switches/aps) and proxies(mxedge) are configured to reach mist-nac via IPv4
        "use_ip_version": "v4",  // v4 (default) / v6 / v4+v6

        // use this IDP when no explicit realm present in the incoming
        // username/CN OR when no IDP is explicitly mapped to the incoming realm.
        "default_idp_id": "4c441a74-d0de-32c4-78a7-a05e00d080ae",

        "idps": [
            {
                "id": "4c441a74-d0de-32c4-78a7-a05e00d080ae",

                // which realm should trigger this IDP
                "user_realms": [ "abc" ],

                // we extract user realm from
                // 1. Username-AVP (`mist.com` from john@mist.com)
                // 2. Cert CN
            }.
            {
                // mxedge-proxy (eduroam) type IDP
                "id": "5c441a74-d0de-32c4-78a7-a05e00d080af",

                // which realm should trigger this IDP
                "user_realms": [ "*.edu" ],

                // we extract user realm from
                // 1. Username-AVP (`stanford.com` from anonymous@stanford.edu)

                // when the IDP of mxedge-proxy type, exclude the following realms from proxying
                // in addition to other valid home realms in this org
                "exclude_realms": [
                  "stanford.edu"
                ],
            }.
            ...
        ],
        // the CA certs we use to verify client certs
        "cacerts": [
            ""-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
            ...
        ],
        // radius server cert to be presented in EAP TLS
        "server_cert": {
            "cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
            "key": "-----BEGIN PRI...",
            // private key password (optional)
            "password": "****"
        },

        // eap ssl security level
        // see https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_security_level.html#DEFAULT-CALLBACK-BEHAVIOUR
        "eap_ssl_security_level": 2,  // 2 (default), 1 - 4

        // disable RSAE encryption algorithms forcefully
        // see https://www.openssl.org/docs/man3.0/man1/openssl-ciphers.html
        "disable_rsae_algorithms": false, // true - to disable RSAE_PSS_SHA256, RSAE_PSS_SHA384, RSAE_PSS_SHA512 from server side

        // allow customer to choose the EAP-TLS client certificate's field to use for IDP User Groups lookup
        “idp_user_cert_lookup_field”: automatic (default) // email, upn, cn

        // allow customer to choose the EAP-TLS client certificate's field to use for IDP Machine Groups lookup
        “idp_machine_cert_lookup_field”: automatic (default) // cn, dns
    },

    "gateway_mgmt": {
        "app_usage": true,
        "app_probing": {
            "apps": [
                "facebook" // app-keys from /const/applications
            ]
        },

        "overlay_ip": {
            // when it's going overlay, a routable IP to overlay will be required
            "ip": "172.16.10.5",
            // for SSR HA cluster, another IP for node1 will be required, too 
            "node1_ip": "172.16.10.6"
        },
        // optional, for some of the host-out traffic, the path preference can be specified
        // by default, ECMP will be used from all available route/path
        // available services: dns/mist/ntp
        "host_out_policies": {
            "dns": {
                "path_preference": "dc_only"
            },
            "ntp":
                "path_preference": "broadband_wans"
            },
            "syslog":
                "path_preference": "broadband_wans",
                // if different path_preference is desired for each syslog server
                // see `remote_syslog`
                "servers": [
                    {
                        "server_name": "dc_syslog_server",
                        "path_preference": "dc_only"
                    }
                ]
            }
        },
        "host_in_policies": {
            "icmp": {
                "tenants": [
                    "datacenter",
                    "wan-net-1"
                ]
            },
            "snmp": {
                "tenants": [
                    "wan-net-2"
                ]
            }
        }
        "fips_enabled": true // default is false
    },

    // junos_shell_access: Manages role-based web-shell access. 
    // when junos_shell access is not defined (Default) - No additional users are configured and web-shell uses default `mist` user to login.
    // when junos_shell_access is defined - Additional users mist-web-admin (admin permission), mist-web-viewer(viewer permission) are configured on the device and web-shell logs in with the mist-web-admin/mist-web-viewer user depending upon the shell access level. Setting the shell access level to "none", disables web-shell access for that specific role.
    "junos_shell_access": {
        "admin": "admin",  // admin (default) / viewer / none
        "write": "admin",  // admin (default) / viewer / none
        "read": "none"  // viewer / none (default)
        "helpdesk": "none" // viewer / none (default)
    },

    "synthetic_test": {
        "disabled": true, // default is false (i.e. enabled)

        "aggressiveness": "auto",  // auto (default) / high / low



        // allow user to test custom
        "custom_probes": {
            "connectivity-to-dc2": {
                "type" : "icmp”; // icmp / curl / tcp
                // if type = icmp / tcp
                "host": "internal.host",
                // if type = tcp
                "port": 443,

                // if type=curl 
                "url": "https://10.3.5.1:8080/about”, // can be url or IP

                "aggressiveness": "auto", // auto (default) / high / low / med
                "threshold": 100  // milliseconds
            }        
        },

        "tests": [
            {
                "probes": ["app1", "app2"],
                "vlan_ids": [1, 2, 3],
                "lan_networks": ["nw-1", "nw-2"]
            },
            {
                "probes": ["app3"],
                "lan_networks": ["nw-1", "nw-4"]
            },
            {
                "probes": ["app4"],
                "vlan_ids": [1, 2, 10, 15],
            }
        ],

        "wan_speedtest": {
            "enabled": false,  // default is false (i.e. disabled)

            // optional
            // by default, we'll look at the tarffic pattern and determine when to run automatically 
            "time_of_day": "02:00"
        }
    },

    // marvis
    "marvis": {
        "auto_operations": {
            // default are all false
            "bounce_port_for_abnormal_poe_client": false,
            "disable_port_when_rogue_dhcp_server_detected": false,
            "disable_port_when_ddos_protocol_violation": false
        }
    },

    "vpn_options": {
        "as_base": 65000,  // 1-4294967295, default is 65000,
        "enable_ipv6": true,  // default is false
        "st_subnet": "10.224.0.0/12"  // default is 10.224.0.0/12, requiring /12 or bigger to support 16 private IPs for 65535 gateways
    },

    "juniper": {
        "linked": true,
        "customer_name": "Corp NMO"
    },

    // t128 ssr
    "ssr": {
        "conductor_hosts": [ "1.1.1.1", 2.2.2.2" ],
        "conductor_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwc2siOiIxMj",
        "disable_stats": false,
        // auto_upgrade device first time it is onboarded
        "auto_upgrade": {
            "enabled": true,
            "channel": "stable",
            "custom_versions": {
                "SSR120": "5.3.0-93",
                "SSR130": "6.3.0-107.r1",
            }
        }
        "proxy": {
              "url": "http://proxy.internal:8080/"
        }
    },

    "jcloud": {
        "org_id": "<jcloud_org_id>",
        "org_apitoken", "<jcloud_token>",
        "org_apitoken_name", "<jcloud_token_name>"
    },

    "jcloud_ra": {
        "org_id": "<jcloud_org_id>",
        "org_apitoken", "<jcloud_token>",
        "org_apitoken_name", "<jcloud_token_name>"
    },

    "switch": {
        // auto_upgrade device first time it is onboarded
        "auto_upgrade": {
            "enabled": true,
            "snapshot": true, // default is false
            "custom_versions": {
                "QFX5130-32CD": "23.4R2-S2.3",
                "QFX5120-32C": "23.4R2-S2.1",
            }
        }
    },

    "juniper_srx": {
        // auto_upgrade device first time it is onboarded
        "auto_upgrade": {
            "enabled": true,
            "snapshot": true, // default is false
            "custom_versions": {
                "SRX4700": "23.4R2-S2.3",
                "SRX4600": "23.4R2-S2.1",
            }
        }
    },
}

Parameters

Auto Site Assignment can be enabled to automatically assign APs to sites. Once enabled, when an AP in the Org inventory is seen online (e.g. freshly installed), we will try to use the criteria defined to identify the Site Name. Only when a non-empty Site Name is identified and the Site exists, the AP will be assigned to the site.

Automatic Device Naming

Automatic Device Naming works along with Automatic Site Assignment. When an AP that’s already assigned to a site that has no name, we will try to use the criteria defined to name the device. Only when a non-empty Name is identified and no AP with the same name exists in the same Site, the AP will be assigned the name.

Update Org Setting

PUT /api/v1/orgs/:org_id/setting

Reevaluate Auto Assignment

POST /api/v1/orgs/:org_id/inventory/reevaluate_auto_assignment

Response if successful

Status: 200 OK

Set up Custom PCAP Bucket

Setting up Custom PCAP Bucket Involves the following:

1. provide the bucket name
2. we’ll attempt to write a file MIST_TOKEN
3. you have to verify the ownership of the bucket by providing the content of the MIST_TOKEN

Provide Customer Bucket Name

POST /api/v1/orgs/:org_id/setting/pcap_bucket/setup

Request

{
    "bucket": "company-private-pcap"
}

Response if failed

{
    "bucket": "company-private-pcap",
    "detail": "failed to write bucket - 403 AccessDenied"
}

Verify Customer PCAP Bucket

POST /api/v1/orgs/:org_id/setting/pcap_bucket/verify

Request

{
    "bucket": "company-private-pcap",
    "verify_token": "eyJhbGciOiJIUzI1J9.eyJzdWIiOiIxMjM0joiMjgxOG5MDIyfQ.2rzcRvMA3Eg09NnjCAC-1EWMRtxAnFDM"
}

Response if successful

Status: 200 OK

NOTE: a “VERIFIED” file will be created in the bucket

Get Org Certificates

GET /api/v1/orgs/:org_id/cert

Response

{
    "cert": "-----BEGIN CERTIFICATE-----\nMIIowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----"
    // If the current Org CA certificate is set to expire within 30 days, \
    // a pending certificate will be returned along with the expected auto-renewal timestamp.
    "pending_cert": "-----BEGIN CERTIFICATE-----\nMIIowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
    "pending_cert_expiry": 2044471109,
}

Clear Org Certificates

POST /api/v1/orgs/:org_id/cert/regenerate

Rotate Org Certificates

Replace the current org cert with the pending cert generated previously

POST /api/v1/orgs/:org_id/cert/apply_pending

Get Org CRL file

GET /api/v1/orgs/:org_id/crl

Truncate Org CRL file

By default, all certs used by recently unclaimed devices within 9 month will be included in CRL. If the list grows too big, you can truncate it

POST /api/v1/orgs/:org_id/crl/truncate

Request

{
    "days": 30  // default is 30
}

Get Org SSL proxy Certificates

GET /api/v1/orgs/:org_id/ssl_proxy_cert

Response

{
    "cert": "-----BEGIN CERTIFICATE-----\nMIIowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----"
}

Get Org Level OAuth Application Authorization Url

GET /api/v1/orgs/:org_id/setting/:app_name/link?forward=:forward_url // This is kept for backward compatibility

GET /api/v1/orgs/:org_id/setting/:app_name/link_accounts?forward=:forward_url

Parameters

Response

{
    "linked": true,
    "accounts": [
      {
        "account_id": "KkEM7orQSIWHZNFzwMLuRA",
        "last_sync": 1665465339,
        "last_status": "success",
        "linked_by": "Testname1",
        "company": "Test Compay1 Ltd",
        "max_daily_api_requests": 1500 // This field is specific to Zoom app
      },
      {
        "account_id": "kojzWgIJQ0ujR73VvydOdg",
        "last_sync": 1665465346,
        "last_status": "failed",
        "linked_by": "Testname2",
        "company": "Test Compay2 Ltd",
        "error": "OAuth token refresh failed, please re-link your account",
        "errors": ["OAuth token refresh failed, please re-link your account", "API daily rate limit reached for your account"],
        "max_daily_api_requests": null, // This field is specific to Zoom app
      },
      {
        "account_id": "iojzXIJWEuiD73ZvydOfg",
        "last_sync": "failed",
        "last_status": 1665465538,
        "linked_by": "Testname3",
        "company": "Test Compay3 Ltd",
        "max_daily_api_requests": 3500 // This field is specific to Zoom app
      }
    ],
    "authorization_url": "https://zoom.us/oauth/authorize?response_type=code&client_id=YDyajBmJREjwkyb3TPAbA&redirect_uri=https%3A%2F%2Fapi.local%2Fapi%2Fv1%2Forg%2Fb4e16c72-d50e-4c03-a952-a3217e231e2c%2Foauth2%2Fapp%2Fzoom%2Fcallback&state=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE2NDk3NjE0MDQsImZvcndhcmQiOiJodHRwczovL2NsaWVudGZvcndhcmR1cmwuY29tIn0.RIE4XTU5kpF4nKIy7_enJ0PpOCyTTp6DLm9PZsdncpI"
}

Definitions

Delete Org Level OAuth Application Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/:app_name/link // This is kept for backward compatibility

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

DELETE /api/v1/orgs/:org_id/setting/:app_name/link_accounts // kept for backward compatibility

Request Payload

{
    "account_id": "iojzXIJWEuiD73ZvydOfg"
}

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

DELETE /api/v1/orgs/:org_id/setting/:app_name/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Update The Third Party Apps Accounts Org Settings

PUT /api/v1/orgs/:org_id/setting/:app_name/link_accounts

Request Payload, These Field And Values Will Be Specific To Each Of The Third Party Apps Accounts.

Request Payload For Zoom App

{
    "account_id": "iojzXIJWEuiD73ZvydOfg",
    "max_daily_api_requests": 5000
}

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Get Juniper Linked Accounts

GET /api/v1/orgs/:org_id/setting

Response

{
    ...
    "juniper": {
        "accounts": [
            {
                "name": "ABC Corp",
                "linked_by": "John Smith (john@abccorp.com)"
            }
        ]
    }
}

Link Juniper Accounts

POST /api/v1/orgs/:org_id/setting/juniper/link_accounts

Request Payload

{
    "username": "john@nmo.com",
    "password": "password"
}

Response if Account linked

Status 200 OK

{
    "account": {
        "name": "ABC Corp",
        "linked_by": "John Smith (john@abccorp.com)"
    }
}

Response if account already linked

Status 400 BadRequest

{
    "detail": "Account[ABC Corp] already linked",
}

Unlink Juniper Customer ID

DELETE /api/v1/orgs/:org_id/setting/juniper/linked_account

Request

{
    "account_name": "ABC Corp"

    // required only if there are duplicate account_names
    "linked_by": "John Smith (john@abccorp.com)"
}

Setup CradlePoint Connection to Mist

This sets up Cradlepoint webhooks to send events to Mist

POST /api/v1/orgs/:org_id/setting/cradlepoint/setup

Payload

{
    "ecm_api_id": "73446d61-2206-4ea5-855a-0043f980be62",
    "ecm_api_key": "68b329da9893e34099c7d8ad5cb9c9405",
    "cp_api_id": "84446d61-2206-4ea5-855a-0043f980be54",
    "cp_api_key": "79c329da9893e34099c7d8ad5cb9c941",
}

Update CradlePoint Connection to Mist

This updates the Cradlepoint integration settings in Mist

PUT /api/v1/orgs/:org_id/setting/cradlepoint/setup

Payload

{
    "ecm_api_id": "73446d61-2206-4ea5-855a-0043f980be62",
    "ecm_api_key": "68b329da9893e34099c7d8ad5cb9c9405",
    "cp_api_id": "84446d61-2206-4ea5-855a-0043f980be54",
    "cp_api_key": "79c329da9893e34099c7d8ad5cb9c941",
}

Delete CradlePoint Connection to Mist

This deletes the Cradlepoint integration in Mist

DELETE /api/v1/orgs/:org_id/setting/cradlepoint/setup

Test CradlePoint Connection to Mist

This tests the Cradlepoint integration in Mist

GET /api/v1/orgs/:org_id/setting/cradlepoint/setup

Response

{
    "last_status": "inactive",
    "error": "Cradlepoint API keys are no longer valid, please verify and update the keys under organization settings."
}

Definitions

Sync CradlePoint Routers

This syncs cradlepoint devices with Mist. We’ll also attempt to use the LLDP data from cradlepoint to identify the linkage against Mist Site / Device

POST /api/v1/orgs/:org_id/setting/cradlepoint/sync

Update OtherDevice

If the Site / Device cannot be identified, a manual association can be made

PUT /api/v1/orgs/:org_id/otherdevices/:mac

Request

{
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "device_mac": "0adfea67e65b"
}

Update OtherDevices

Assign or unassign OtherDevices to and from a site.

PUT /api/v1/orgs/:org_id/otherdevices

Parameters

Request

{
    "op": "assign",
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "macs": [
        "5c5b350e0001",
        "5c5b350e0003"
    ]
}

Get OtherDevices

GET /api/v1/orgs/:org_id/otherdevices?vendor=:vendor

Response

[
    {
        "id": "ae9dee49-69e7-4710-a114-5b827a777738",
        "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
        "created_time": 1676983730,
        "modified_time": 1676983730,
        "vendor": "cradlepoint",
        "mac": "5c5b35000018",
        "serial": "FXLH2015150025",
        "model": "AP41",
        "name": "hallway",
        "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
        "device_mac": "001122334455"
    }
]

Get OtherDevice

GET /api/v1/orgs/:org_id/otherdevice/:mac

Response

{
    "id": "ae9dee49-69e7-4710-a114-5b827a777738",
    "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
    "vendor": "cradlepoint",
    "mac": "5c5b35000018",
    "serial": "WB23015E025468",
    "model": "W2005",
    "name": "W2005-268",
    "vendor_api_id": "4658714",
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "device_mac": "001122334455",
    "state": "online"
}

Delete OtherDevice

DELETE /api/v1/orgs/:org_id/otherdevices/:mac

Get Otherdevice Stats

GET /api/v1/orgs/:org_id/stats/otherdevices/:mac

Response

{
    "vendor": "cradlepoint",
    "mac": "0030448f1f44",
    "uptime": 25065,
    "last_seen": 1736499062,
    "version": "7.24.50",
    "vendor_specific": {
        "interfaces": {
            "ethernet-lan": {
                "ip": "192.168.0.1",
                "mode": "lan",
                "link": false,
                "service_mode": "Ethernet",
                "type": "ethernet",
                "uptime": 0,
                "bytes_in": 331068567,
                "bytes_out": 6763536255,
                "display_name": "Primary LAN",
                "port_parent": "Primary LAN"
            },
            "mdm-81ade837": {
                "ip": "12.68.86.17",
                "mode": "wan",
                "link": true,
                "carrier": "AT&T",
                "state": "READY",
                "service_mode": "5G NSA",
                "type": "mdm",
                "uptime": 2464657,
                "bytes_in": 287174553,
                "bytes_out": 306774804,
                "rssi": -79,
                "rsrp": -109.0,
                "rsrq": -15.0,
                "sinr": 3.4,
                "imei": "650994581483248",
                "imsi": "410410436288436",
                "mtu": 1400,
                "display_name": "Internal 5GB (SIM1)"
            },..
        }
    },
    "cached_stats": true,
    "lldp_enabled": true,
    "connected_devices": {}
}

Reboot OtherDevice

POST /api/v1/orgs/:org_id/otherdevices/:mac/reboot

Payload

{}

Subscribe to OtherDevice sync events

WS /api-ws/v1/stream

Request

{
    "subscribe": "/orgs/:org_id/otherdevices/sync"
}

Response

{
    "event": "data"
    "channel": "/orgs/67970e46-4e12-11e6-9188-0242ac110007/otherdevices/sync"
    "data": {
        "vendor": "cradlepoint"
        "status": "failed",
        "text": "Cannot sync devices, please verify API keys under organization setting."
    }
}

Definitions

Get Jamf Application Linked Status

GET /api/v1/orgs/:org_id/setting/jamf/link_accounts

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "account_id": "ae9dee49-69e7-4710-a114-5b827a777738",
        "instance_url": "junipertest.jamfcloud.com",
        "smartgroup_name": "CompliantGroup1",
        "last_sync": 1665465339000,
        "last_status": "success",
        "linked_by": "Testname1",
        "name": "Test Compay1 Ltd"
      },
      {
        "account_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",
        "instance_url": "junipernfr.jamfcloud.com", // Linked Jamf Instance URL
        "smartgroup_name": "CompliantGroup", // smartgroup name to determine compliance status
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that pull Jamf account data
        "last_status": "failed", // Is the last data pull for Jamf account is successful or not
        "linked_by": "Testname2", // First name of the user who linked the Jamf account
        "name": "Test Compay2 Ltd", // Name of the company whose Jamf account mist has subscribed to
        "error": "Get token failed, please re-link jamf" // This error is provided when the Jamf account fails to fetch token/data
      }
    ]
}

Definitions

Add Jamf Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/jamf/link_accounts

Request Payload

{
    "instance_url": "customer account Jamf instance URL"
    "client_id": "customer account api client id",
    "client_secret": "customer account api client secret",
    "smartgroup_name": "smart group membership for determining compliance status"
}

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "account_id": "ae9dee49-69e7-4710-a114-5b827a777738",
        "instance_url": "junipertest.jamfcloud.com",
        "smartgroup_name": "CompliantGroup1",
        "last_sync": 1665465339000,
        "last_status": "success",
        "linked_by": "Testname1",
        "name": "Test Compay1 Ltd"
      },
      {
        "account_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",     // generated account id (uuid)
        "instance_url": "junipernfr.jamfcloud.com", // Linked Jamf Instance URL
        "smartgroup_name": "CompliantGroup", // smartgroup name to determine compliance status
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that pull Jamf account data
        "last_status": "failed", // Is the last data pull for Jamf account is successful or not
        "linked_by": "Testname2", // First name of the user who linked the Jamf account
        "name": "Test Compay2 Ltd", // Name of the company whose Jamf account mist has subscribed to
        "error": "Get token failed, please re-link jamf" // This error is provided when the Jamf account fails to fetch token/data
      }
    ]
}

Definitions

Status: 200 Successful
Status: > 400 Unsuccessful

Delete Jamf Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/jamf/link_accounts // kept for backward compatibility

Request Payload

{
    "account_id": "ae9dee49-69e7-4710-a114-5b827a777738"
}

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

DELETE /api/v1/orgs/:org_id/setting/jamf/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Get VMware Application Linked Status

GET /api/v1/orgs/:org_id/setting/vmware/link_accounts

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "account_id": "f43ea4c4-8a97-4159-9214-112a8c7b8f22",
        "instance_url": "as800.airwatchportals.com",
        "webhook_enabled": true,
        "webhook_url": "https://websync.nac-staging.mistsys.com/v1/S_41b2525af1d8dcbe9005/f43ea4c48f22/vmware/mdm",
        "webhook_auth_type": "Basic",
        "webhook_username": "username_1234", 
        "webhook_password": "password_1234",
        "last_sync": 1665465339000,
        "last_status": "success",
        "linked_by": "Testname1",
        "name": "Test Compay1 Ltd",
        "linked_timestamp": 1702284364
      },
      {
        "account_id": "m56ea4c4-8a10-4189-9214-113a8c7b8m82",
        "instance_url": "as561.airwatchportals.com", // Linked VMware Instance URL
        "webhook_enabled": true,
        "webhook_url": "https://websync.nac-staging.mistsys.com/v1/S_41b2525af1d8dcbe9005/f43ea4c48f22/vmware/mdm",
        "webhook_auth_type": "Basic",
        "webhook_username": "username_1234", 
        "webhook_password": "password_1234",
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that pull VMware account data
        "last_status": "failed", // Is the last data pull for VMware account is successful or not
        "linked_by": "Testname2", // First name of the user who linked the VMware account
        "name": "Test Compay2 Ltd", // Name of the company whose VMware account mist has subscribed to
        "linked_timestamp": 1702284364
        "error": "Get token failed, please re-link VMware" // This error is provided when the VMware account fails to fetch token/data
      }
    ]
}

Definitions

Add VMware Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/vmware/link_accounts

Request Payload

{
    "instance_url": "customer account VMware instance URL"
    "client_id": "customer account api client id",
    "client_secret": "customer account api client secret",
    "webhook_enabled": true
}

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "account_id": "f43ea4c4-8a97-4159-9214-112a8c7b8f22",
        "instance_url": "as800.airwatchportals.com",
        "webhook_enabled": true,
        "webhook_url": "https://websync.nac-staging.mistsys.com/v1/S_41b2525af1d8dcbe9005/f43ea4c48f22/vmware/mdm",
        "webhook_auth_type": "Basic",
        "webhook_username": "username_1234", 
        "webhook_password": "password_1234",
        "last_sync": 1665465339000,
        "last_status": "success",
        "linked_by": "Testname1",
        "name": "Test Compay1 Ltd",
        "linked_timestamp": 1702284364
      },
      {
        "account_id": "m56ea4c4-8a10-4189-9214-113a8c7b8m82",
        "instance_url": "as561.airwatchportals.com", // Linked VMware Instance URL
        "webhook_enabled": true,
        "webhook_url": "https://websync.nac-staging.mistsys.com/v1/S_41b2525af1d8dcbe9005/f43ea4c48f22/vmware/mdm",
        "webhook_auth_type": "Basic",
        "webhook_username": "username_1234", 
        "webhook_password": "password_1234",
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that pull VMware account data
        "last_status": "failed", // Is the last data pull for VMware account is successful or not
        "linked_by": "Testname2", // First name of the user who linked the VMware account
        "name": "Test Compay2 Ltd", // Name of the company whose VMware account mist has subscribed to
        "linked_timestamp": 1702284364
        "error": "Get token failed, please re-link VMware" // This error is provided when the VMware account fails to fetch token/data
      }
    ]
}

Definitions

Status: 200 Successful
Status: > 400 Unsuccessful

Update VMware Application With Mist Portal

PUT /api/v1/orgs/:org_id/setting/vmware/link_accounts/:account_id

Request Payload

{
    "webhook_enabled": False
}

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Delete VMware Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/vmware/link_accounts // kept for backward compatibility

Request Payload

{
    "account_id": "f43ea4c4-8a97-4159-9214-112a8c7b8f22"
}

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

DELETE /api/v1/orgs/:org_id/setting/vmware/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Get MobiControl Application Linked Status

GET /api/v1/orgs/:org_id/setting/mobicontrol/link_accounts

Parameters

Response

{
    "linked": True, 
    "accounts": [
            {
                "account_id": "7f80cd00-40b1-49e5-b2cb-9386d89af0d6", 
                "instance_url": "https://a0020372.mobicontrol.cloud", 
                "client_id": "3e408b13255844149f2830e8609fe8f3"
                "last_sync": 1665465339000, 
                "last_status": "success", 
                "linked_by": "User1", 
                "linked_timestamp": 1702284364, 
                "name": "Company1 Ltd.", 
            }, 

            {
                "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359", 
                "instance_url": "https://a0032314.mobicontrol.cloud", // Linked MobiControl Instance URL
                "client_id": "e81cfb1980454b4bb6109c74136ca528" //Linked MobiControl Client Id
                "last_sync": 1234567890123, // Last data pull timestamp, background jobs that pull MobiControl account data
                "last_status": "failed", // Is the last data pull for MobiControl account is successful or not
                "linked_by": "User2", // First name of the user who linked the MobiControl account
                "linked_timestamp": 1702284364, 
                "name": "Company2 Ltd.", // Name of the company whose MobiControl account mist has subscribed to
                "error" : "Get token failed, please re-link MobiControl account" // This error is provided when the MobiControl account fails to fetch token/data
            }
        ]
}

Definitions

Add MobiControl Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/mobicontrol/link_accounts

Request Payload

{
    "instance_url" : "Customer account MobiControl instance URL",
    "client_id" : "Customer account API client ID",
    "client_secret" : "Customer account API client Secret",
    "username" : "Customer account username",
    "password" : "Customer account password"
}

Parameters

Response

{
    "linked": True, 
    "accounts": [
            {
                "account_id": "7f80cd00-40b1-49e5-b2cb-9386d89af0d6", 
                "instance_url": "https://a0020372.mobicontrol.cloud", 
                "client_id": "3e408b13255844149f2830e8609fe8f3"
                "last_sync": 1665465339000, 
                "last_status": "success", 
                "linked_by": "User1", 
                "linked_timestamp": 1702284364, 
                "name": "Company1 Ltd.", 
            }, 

            {
                "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359", // Generated account id (uuid)
                "instance_url": "https://a0032314.mobicontrol.cloud", // Linked MobiControl Instance URL
                "client_id': 'e81cfb1980454b4bb6109c74136ca528' //Linked MobiControl Client Id
                'last_sync': 1234567890123, // Last data pull timestamp, background jobs that pull MobiControl account data
                'last_status': 'failed', // Is the last data pull for MobiControl account is successful or not
                'linked_by': 'User2', // First name of the user who linked the MobiControl account
                'linked_timestamp': 1702284364, 
                'name': 'Company2 Ltd.', // Name of the company whose MobiControl account mist has subscribed to
                'error' : 'Get token failed, please re-link MobiControl account' // This error is provided when the MobiControl account fails to fetch token/data
            }
        ]
}

Definitions

Status: 200 Successful
Status: > 400 Unsuccessful

Delete MobiControl Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/mobicontrol/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Get Linked ZDX Accounts

GET /api/v1/orgs/:org_id/setting/zdx/link_accounts

Parameters

Response

{
    "linked": true,
    "accounts": [
        {
            "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359", // Generated account id (uuid)
            "key_id": "L72frZcK3JvrZc",
            "webhook_url": "https://webhook.url/xxx",    // Webhook url to notify Mist about a ZDX alert
            "zdx_org_id": "123456",
            "cloud_name": "zdxcloud.net"
        },
        {
            "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359",
            "key_id": "K35vrZcK3JvrZc",
            "webhook_url": "https://webhook.url/yyy",
            "zdx_org_id": "4601412",
            "cloud_name": "zdxcloud.net"
        }
    ]
}

Add ZDX Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/zdx/link_accounts

Parameters

Delete ZDX Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/zdx/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Link Prisma Account

POST /api/v1/orgs/:org_id/setting/prisma/link_accounts

Request

{
  "client_id": "mist-integration@18995xxxx.iam.panserviceaccount.com",
  "client_secret": "07519xxx-fb64-xxxx-xxxx-xxxx4af3384",
  "tsg_id": "189953456",
  "enable_probe": true,
  "auto_probe_subnet": "11.0.0.0/8"
}

Parameters

Response

{
    "linked": true,
    "accounts": [
        {
            "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359",   // Generated account id (uuid)
            "tsg_id": "189953456",
            "service_account_name": "Corp SA",
            "cloud_name": "api.sase.paloaltonetworks.com",
            "region": "americas",
            "enable_probe": true,
            "auto_probe_subnet": "11.0.0.0/8",
            "service_connections": {},
            "regions": {}
        }
    ]
}

Update Prisma Account

PUT /api/v1/orgs/:org_id/setting/prisma/link_accounts/:account_id

Request

{
  "enable_probe": true,
  "auto_probe_subnet": "11.0.0.0/8"
}

Parameters

Response

{
    "linked": true,
    "accounts": [
        {
            "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359",
            "tsg_id": "189953456",
            "service_account_name": "Corp SA",
            "cloud_name": "api.sase.paloaltonetworks.com",
            "region": "americas",
            "enable_probe": true,
            "auto_probe_subnet": "11.0.0.0/8"
        }
    ]
}

Get Linked Prisma Accounts

GET /api/v1/orgs/:org_id/setting/prisma/link_accounts

Parameters

Response

{
    "linked": true,
    "accounts": [
        {
            "account_id": "80364a28-7ccc-4746-b110-ecf3dfd3a359",   // Generated account id (uuid)
            "tsg_id": "189953456",
            "service_account_name": "Demo SA",
            "cloud_name": "api.sase.paloaltonetworks.com",
            "region": "americas",
            "enable_probe": true,
            "auto_probe_subnet": "11.0.0.0/8",
            "service_connections": {
                 "MCD_LAB_SC_1": {
                      "region": "us-west-1"
                 }
            },
            // regions configured under this account
            "regions": {
                 "us-west-1": {
                      "allocated_bandwidth": 50  // Mbps
                      "aggregate_region": "us-southwest"   // Bandwidth Aggregate region for this region
                      "name": "US West"  // Display name for this region
                 }
            }
        },
        {
            "account_id": "80364a28-7ccc-4746-b110-5678aafd65cc",
            "tsg_id": "189954023",
            "service_account_name": "Corp SA",
            "cloud_name": "api.sase.paloaltonetworks.com",
            "enable_probe": false,
            "auto_probe_subnet": null,
            "service_connections": {
                 "MCD_LAB_SC_2": {
                      "region": "us-east"
                 }
            },
            // regions configured under this account
            "regions": {
                 "us-east": {
                      "allocated_bandwidth": 100 // Mbps
                      "aggregate_region": "us-northeast"   // Bandwidth Aggregate region for this region
                      "name": "US Northeast"  // Display name for this region
                 }
            }
        }
    ]
}

Unlink Prisma Account

DELETE /api/v1/orgs/:org_id/setting/prisma/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Get CrowdStrike Application Linked Status

GET /api/v1/orgs/:org_id/setting/crowdstrike/link_accounts

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "last_status": "success",
        "last_sync": 1665465339000,
        "account_id": "ae9dee49-69e7-4710-a114-5b827a777738",
        "linked_by": "Testname1",
        "name": "Test Company1 Ltd"
        "linked_timestamp":1728275689.284758,
      },
      {
        "last_status": "failed", // Is the last data pull for crowdstrike account is successful or not
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that that pull CrowdStrike account data
        "account_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5", //uuid generated
        "linked_by": "Testname2", // First name of the user who linked the crowdstrike account
        "name": "Test Company2 Ltd", // Name of the company whose crowdstrike account mist has subscribed to
        "linked_timestamp":1728275689.284758, // Timestamp when the account is linked
        "error": "Get token failed, please re-link crowdstrike" // This error is provided when the crowdstrike account fails to fetch token/data
      }
}

Definitions

Add CrowdStrike Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/crowdstrike/link_accounts

Request Payload

{
    "customer_id": "customer id of an admin"
    "client_id": "customer account api client id",
    "client_secret": "customer account api client secret",
}

Parameters

Response

{
    "linked": true,
    "accounts": [
     {
        "last_status": "success",
        "last_sync": 1665465339000,
        "account_id": "ae9dee49-69e7-4710-a114-5b827a777738",
        "linked_by": "Testname1",
        "name": "Test Company1 Ltd"
        "linked_timestamp":1728275689.284758,
      },
      {
        "last_status": "failed", // Is the last data pull for crowdstrike account is successful or not
        "last_sync": 1234567890123, // Last data pull timestamp, background jobs that that that pull CrowdStrike account data
        "account_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5", //uuid generated
        "linked_by": "Testname2", // First name of the user who linked the crowdstrike account
        "name": "Test Company2 Ltd", // Name of the company whose crowdstrike account mist has subscribed to
        "linked_timestamp":1728275689.284758, // Timestamp when the account is linked
        "error": "Get token failed, please re-link crowdstrike" // This error is provided when the crowdstrike account fails to fetch token/data
      }
    ]
}

Definitions

DELETE /api/v1/orgs/:org_id/setting/crowdstrike/link_accounts/:account_id

Parameters

Response

{Status: 200 Successful}
Status: > 400 Unsuccessful

Add SentinelOne Authorization With Mist Portal

POST /api/v1/orgs/:org_id/setting/sentinelone/link_accounts

Request Payload

{
    "instance_url": "customer account SentinelOne instance URL"
    "api_token": "customer account api token",
}

Parameters

Response

{
    "linked": True,
     "accounts": [
        {
            "account_id": "00fd8b39-cf92-4b43-a2ff-a461b48e7059",
            "instance_url": "usea1-015.sentinelone.net"
            "linked_by": "user1@test.com",
            "last_status": "success",
            "last_sync": 1234567891,
            "name": "company1",
            "linked_timestamp": 1234567891,
        },
        {
            "account_id": "00fd8b39-cf92-4b43-a2ff-a461b48e7060",
            "instance_url": "usea1-017.sentinelone.net"//Linked SentinelOne instance URL
            "linked_by": "user2@test.com",//user who linked the SentinelOne account
            "last_status": "failed", //Is the last data bull for SentinelOne account is successful or not
            "last_sync": 1234567800, //Lastpull timestamp , background jobs that pull SentinelOne account data
            "name": "company2", //Name of the company whose SentinelOne account mist has subscribed to
            "linked_timestamp": 1234567891,
            "error" : "Get token failed, please re-link SentinelOne account" // This error is provided when the SentinelOne account fails to fetch token/data
        }
    ]
}

Definitions

Status: 200 Successful
Status: > 400 Unsuccessful

Delete SentinelOne Authorization With Mist Portal

DELETE /api/v1/orgs/:org_id/setting/sentinelone/link_accounts/:account_id

Parameters

Response

Status: 200 Successful
Status: > 400 Unsuccessful

Setup Zscaler Integration

in Zscaler UI 1. add Partner Integration at https://admin.zscalerbeta.net/#administration/partner-integration 2. Add Partner Administrator Role at https://admin.zscalerbeta.net/#administration/role-management - Name: Mist - Access: Full 3. add Partner Admin at https://admin.zscalerbeta.net/#administration/admin-management with - Login ID: john - email: john@abc.com 4. Find the cloud name for ZIA https://help.zscaler.com/zia/what-my-cloud-name-zia

To setup Zscaler credential

POST /api/v1/orgs/:org_id/setting/zscaler/setup

{
    "partner_key": "K35vrZcK3JvrZc",
    "username": "john@abc.com",
    "password": "foryoureyesonly",
    "cloud_name": "zscalerbeta.net"
}

To get Zscaler credential

GET /api/v1/orgs/:org_id/setting/zscaler/setup

Response

{
    "partner_key": "abcd12cK3JvrZc",
    "username": "john@abc.com",
    "cloud_name": "zscalerbeta.net"
}

To delete Zscaler

DELETE /api/v1/orgs/:org_id/setting/zscaler/setup

Setup JSE Integration

in JSE UI 1. Create custom role with Read access to service-location and RW access to site and IPSec profile APIs. 2. Create a user with the above custom role. - email: john@abc.com 3. Activate the user in the JSE account. 4. Create the service locations on the JSE account.

To setup JSE

POST /api/v1/orgs/:org_id/setting/jse/setup

{
    "username": "john@abc.com",
    "password": "foryoureyesonly",
    "cloud_name": "devcentral.juniperclouds.net"
}

To get JSE information

GET /api/v1/orgs/:org_id/setting/jse/setup

Response

{
    "username": "john@abc.com",
    "cloud_name": "devcentral.juniperclouds.net"
}

To delete JSE credential

DELETE /api/v1/orgs/:org_id/setting/jse/setup

To get JSE info

Retrieves the list of JSE orgs associated with the account.

GET /api/v1/orgs/:org_id/setting/jse/info

Response

{
    "cloud_name": "devcentral.juniperclouds.net"
    "org_names": ["Mist-Sys", "Mist-Eng"]
}

Setup Sky ATP Integration

1. Login to the Sky ATP realm through the Mist UI by providing the realm, username and password.
2. Sky ATP API is invoked which creates the realm using above details.
3. Sky ATP by default will provide functionality for Security-Intelligence and Advanced Anti Malware.
4. Security Intelligence will provide configuration for CC, DNS Feeds, Infected Host, Blocklists and Allowlists.

To create Sky ATP realm

POST /api/v1/orgs/:org_id/setting/skyatp/setup

{
     "realm": "mist-team",
     "username": "john@abc.com",
     "password": "skyatp"
}

To delete Sky ATP

DELETE /api/v1/orgs/:org_id/setting/skyatp/setup

To get Sky ATP

GET /api/v1/orgs/:org_id/setting/skyatp/setup

Response

{
    "realm": "mist-team",
    "username": "john@abc.com",
    // optional -  third party threat feeds/allowlist/blocklist
    "secintel": {
        // juniper secintel_feeds are enabled depending on your license tier: infected_host, geo_ip, attacker_ip, command_and_control

        // third party:
        //   - ip-based: block_list, threatfox_ip, feodo_tracker, dshield, tor
        //   - url-based: threatfox_url, urlhaus, open_phish
        //   - domain-based: threatfox_domains
        "third_party_threat_feeds": [ "block_list" ]
    },
    "secintel_allowlist_url": "https://papi.s3.amazonaws.com/secintel_allowlist/xxx...",
    "secintel_blocklist_url": "https://papi.s3.amazonaws.com/secintel_blocklist/xxx..."
}

Update Sky ATP Third Party Threat Feeds

PUT /api/v1/orgs/:org_id/setting/skyatp/setup

{
    "secintel": {
        // juniper secintel_feeds are enabled depending on your license tier: infected_host, geo_ip, attacker_ip, command_and_control

        // third party:
        //   - ip-based: block_list, threatfox_ip, feodo_tracker, dshield, tor
        //   - url-based: threatfox_url, urlhaus, open_phish
        //   - domain-based: threatfox_domains
        "third_party_threat_feeds": [ "block_list" ]
    }
} 

Update Sky ATP Allowed/Blocked List

PUT /api/v1/orgs/:org_id/setting/skyatp/secintel_allowlist
PUT /api/v1/orgs/:org_id/setting/skyatp/secintel_blocklist

{
    "ip": [
        {
            "value": "10.1.3.5",
            // optional
            "comment": "nas"
        }
    ],
    "domain": [
        {
            "value": "unsafe.xxx",
            // optional
            "comment": "restricted"
        }
    ]
}

Org Webhooks

Base URI

/api/v1/orgs/:org_id/webhooks
/api/v1/orgs/:org_id/webhooks/:webhook_id/ping
/api/v1/orgs/:org_id/webhooks/:webhook_id/events/search
/api/v1/orgs/:org_id/webhooks/:webhook_id/events/count

Example

see Site:Webhooks for schema

N.B. For org webhooks, only alarms/audits/client-info/client-join/client-sessions/device-events/device-updowns/mxedge-events Infrastructure topics are supported.

Installer APIs

In a typical enterprise, a separate group of people, Installers, are responsible for install new devices. May it be a new installation (e.g. new stores), a replacement installation (e.g. replacing Cisco APs with Mist APs), or addition ( e.g. adding new APs for better coverage). Instead of granting them Admin/Write privilege, it’s more desirable to grant them minimum privileges to do the initial provisioning so they cannot read sensible information (e.g. PSK of a WLAN), or change configs of running APs.

At a high level, Installer APs try to achieve the following:

1. identifying a device by MAC (that’s what they see)
2. they can only touch configurations of the devices they’re installing
3. allow the following configurations:
   • name
   • site assignment
   • device profile assignment
   • map and location (x/y) assignment
   • claim (if not already in the inventory)
   • replace existing device with the device being installed

Grace Period

Grace period provides a dynamic way to limit what devices / sites installer can work on. Generally installers work on recent deployments - bringing up new sites, add newly claimed devices to new / existing sites. They make mistakes, too, and may need to further tweak some of the parameters. Default grace period is 7 days and can be set from 1 day to 365 days.

Get List of Devices Recently Claimed

GET /api/v1/installer/orgs/:org_id/devices?limit=100

Supported Filters

Response

X-Page-Limit: 100
X-Page-Page: 1
X-Page-Total: 31
[
    {
        //
        "mac": "5c5b35000018",
        "model": "AP41",
        "serial": "FXLH2015150025",
        "vc_mac": null,

        // from site / profile assignment
        "name": "hallway",
        "site_name": "SJ1",
        "deviceprofile_name": "SJ1",

        // if assigned to a site
        "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",
        "x": 150,
        "y": 300,
        "height": 2.7,
        "orientation": 90,

        // from stats
        "connected": true,
        "last_seen": 1687887907.5919843,
        "uptime": 12345,
        "version": "0.10.24362",
        "ip": "192.168.1.111",
        "ext_ip": "12.34.56.78"
    },
    ...
]

Provision

PUT /api/v1/installer/orgs/:org_id/devices/:mac

Request

{
    "name": "SJ1-AP1",

    // optional
    "deviceprofile_name": "SJ1",

    // optional
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "site_name": "SJ1",

    // optional
    "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",  // has to be in the same site
    "x": 150,
    "y": 300,
    "height": 2.7,
    "orientation": 90,

    // optional role for switch / gateway
    "role": "switch_role",

    // if this is to replace an existing device
    "replacing_mac": "5c5b3500003"
}

If replacing_mac is in the request payload, other attributes are ignored, we attempt to replace existing device (with mac replacing_mac) with the inventory device being configured. The replacement device must be in the inventory but not assigned, and the replacing_mac device must be assigned to a site, and satisfy grace period requirements. The Device replaced will become unassigned.

Response if it was last modified outside of grace period

Status: 400 Bad Request

{
    "detail": "outside of grace period"
}

Failures with replacing device

invalid mac given for replacing_mac:

Status: 400 Bad Request

{
    "detail": "invalid replacing_mac"
}

replacing_mac device is not in org inventory:

Status: 404 Not Found

{
    "detail": "replacing_mac inventory not found"
}

replacing_mac device not found:

Status: 404 Not Found

{
    "detail": "replacing_mac device not found"
}

replacing_mac device last modified outside of grace period:

Status: 400 Bad Request

{
    "detail": "replacing_mac device outside of grace period"
}

replacing_mac device is not assigned to a site:

Status: 400 Bad Request

{
    "detail": "replacing_mac device is unassigned"
}

inventory device is already assigned:

Status: 400 Bad Request

{
    "detail": "device already assigned"
}

Unassign a Device Recently Claimed

DELETE /api/v1/installer/orgs/:org_id/devices/:mac

Claim Devices

This mirrorsPOST /api/v1/orgs/:org_id/inventory (see Inventory API)

POST /api/v1/installer/orgs/:org_id/devices

Request

[
    "6JG8E-PTFV2-A9Z2N",
    "DVH4V-SNMSZ-PDXBR"
]

Get Sites

Get the sites Installer can see / modify. This includes all sites (last modified within the grace period) and the extra_site_ids defined in Org Setting

GET /api/v1/installer/orgs/:org_id/sites

Response

[
    {
        "id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
        "name": "Mist Office",
        "timezone": "America/Los_Angeles",
        "country_code": "US",
        "latlng": { "lat": 37.295833, "lng": -122.032946 },
        "address": "1601 S. Deanza Blvd., Cupertino, CA, 95014"
    }
]

Create or Update a Site

Often the Installers are asked to assign Devices to Sites. The Sites can either be pre-created or created/modified by the Installer. If this is an update, the same grace period also applies.

PUT /api/v1/installer/orgs/:org_id/sites/:site_name

Request

{
    "timezone": "America/Los_Angeles",
    "country_code": "US",
    "latlng": { "lat": 37.295833, "lng": -122.032946 },
    "address": "1601 S. Deanza Blvd., Cupertino, CA, 95014"

    "rftemplate_name": "rftemplate1",
    "sitegroup_names": ["sg1", "sg2"]
}

Get / Update / Create Maps

CRUD APIs for Maps works exactly the same way as those in Sites

GET /api/v1/installer/orgs/:org_id/sites/:site_name/maps
POST /api/v1/installer/orgs/:org_id/sites/:site_name/maps/:id
PUT /api/v1/installer/orgs/:org_id/sites/:site_name/maps/:id
DELETE /api/v1/installer/orgs/:org_id/sites/:site_name/maps/:id

Map Import

Import data from files is a multipart POST which has an file, an optional json, and an optional csv, to create floorplan, assign & place ap if name or mac matches

POST /api/v1/installer/orgs/:org_id/sites/:site_name/maps/import

Request

A multi-part POST

"json": a JSON string, vendor option: ekahau, ibwave, import_all_floorplans: optional, false by default,
import_height: optional, default: true, import_orientation: optional, default: true
"file": a binary file, option: .esx
"csv": a csv file for ap name mapping, optional
// for the JSON payload
{
    "vendor_name": "ekahau",
    "import_all_floorplans": true  // optional
    "import_height": true, // optional
    "import_orientation": false // optional
}

Device Import CSV File Format

Vendor AP name,Mist AP Mac
US Office AP-2 - 5c:5b:35:00:00:02,5c5b35000002

Response

{
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "aps": [
        {
            "mac": "5c5b35000001",
            // placed
            "action": "placed"
            "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5"
            // assigned to a site and placed
            "action": "assigned-placed",
            // named and placed
            "action": "named-placed"
            // assigned, named and placed
            "action": "assigned-named-placed"
            // if we ignore it (did nothing with it)
            "action": "ignored",
            // floorplan id, height, orientation for ignored ap
            "floorplan_id": "cbdb7f0b-3be0-4872-88f9-58790b509c23-j68kows8"
            "orientation": 45,
            "height": 3
            "reason": "not found on site" // "not found in inventory"
        }
    ],
    "floorplans": [
        {
            // whatever ID vendor has
            "id": "cbdb7f0b-3be0-4872-88f9-58790b509c23-j68kows8",
            "name": "map1",
            // we only import the floorplan if at least one of the AP is being placed by default
            "action": "imported",
            "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",
            "action": "ignored",
            "reason": "no aps placed"
        }
    ],
    "summary": {
        "num_ap_assigned": 1,
        "num_map_assigned": 1,
        "num_inv_assigned": 1
    }
}

Locate a Device

Locate a Device by blinking it’s LED, it’s a persisted state that has to be stopped by calling Stop Locating API

POST /api/v1/installer/orgs/:org_id/devices/:mac/locate

Stop Locating a Device

POST /api/v1/installer/orgs/:org_id/devices/:mac/unlocate

Optimize

After installation is considered complete (APs are placed on maps, all powered up), you can trigger an optimize operation where RRM will kick in (and maybe other things in the future) before it’s automatically scheduled.

GET /api/v1/installer/sites/:site_name/optimize

Get VC Status

This mirrors GET /api/v1/sites/:site_id/devices/:device_id/vc (see Virtual Chassis API) where site_id and device_id are replaced with fpc0_mac

GET /api/v1/installer/orgs/:org_id/devices/:fpc0_mac/vc

Form a New Preprovisioned VC

This mirrors POST /api/v1/sites/:site_id/devices/:device_id/vc (see Virtual Chassis API) where site_id and device_id are replaced with fpc0_mac

    POST /api/v1/installer/orgs/:org_id/devices/:fpc0_mac/vc
    {
        "preprovisioned": true,
        "members": [
            {
                "mac": "aff827549235",      // fpc0, same as fpc0_mac
                "vc_role": "master",
                "member_id": 0,
                "vc_ports": ["xe-0/1/0", "xe-0/1/1"]
            },
            {
                "mac": "8396cd006c8c",
                "vc_role": "linecard",
                "member_id": 1,
                "vc_ports": ["xe-0/1/0"],
            },
            {
                "mac": "8396cd00888c",
                "vc_role": "backup",
                "member_id": 2,
                "vc_ports": ["xe-0/1/0"]
            }
        ]
    }

Perprovision VC members

This mirrors PUT /api/v1/sites/:site_id/devices/:device_id/vc (see Virtual Chassis API) where site_id and device_id are replaced with fpc0_mac

add 8396cd00888c as member 2 and enable related vc ports

    PUT /api/v1/installer/orgs/:org_id/devices/:fpc0_mac/vc
    {
        "op": "preprovision",
        "members": [
            {
                "mac": "aff827549235",      // fpc0, same as fpc0_mac of current VC
                "vc_role": "master",
                "member_id": 0,
                "vc_ports": ["xe-0/1/1"]    // enabling vc port xe-0/1/1 on member 0
            },
            {
                "mac": "8396cd006c8c",
                "vc_role": "linecard",
                "member_id": 1
            },
            {
                "mac": "8396cd00888c",
                "vc_role": "backup",
                "member_id": 2,
                "vc_ports": ["xe-0/1/0"]    // enabling vc port xe-0/1/1 on member 2
            }
        ]
    }

Get List of DeviceProfile Names (WIP)

GET /api/v1/installer/orgs/:org_id/deviceprofiles?type=ap

Parameters

Response

[
    {
        "id": "6f4bf402-45f9-2a56-6c8b-7f83d3bc98e9",
        "name: "DeviceProfile 1",
        "type": "ap"  // device type, ap (default) / switch / gateway
    }
]

Attach Device Image (WIP)

Attach up to 3 images to a device

POST /api/v1/installer/orgs/:org_id/devices/:mac/image1
POST /api/v1/installer/orgs/:org_id/devices/:mac/image2
POST /api/v1/installer/orgs/:org_id/devices/:mac/image3

Request

A multi-part POST

"file": a binary file

Remove Device Image (WIP)

Delete background image for Portal

DELETE /api/v1/installer/orgs/:org_id/devices/:mac/image1
DELETE /api/v1/installer/orgs/:org_id/devices/:mac/image2
DELETE /api/v1/installer/orgs/:org_id/devices/:mac/image3

Get List of RFTemplate Names (WIP)

GET /api/v1/installer/orgs/:org_id/rftemplates

Response

[
    {
        "id": "bb8a9017-1e36-5d6c-6f2b-551abe8a76a2",
        "name: "RFTemplate 1"
    }
]

Get List of SiteGroup Names (WIP)

GET /api/v1/installer/orgs/:org_id/sitegroups

Response

[
    {
        "id": "581328b6-e382-f54e-c9dc-999983183a34",
        "name: "SiteGroup 1"
    }
]

Get List of Alarm Templates

GET /api/v1/installer/orgs/:org_id/alarmtemplates

Response

[
    {
        "id": "684dfc5c-fe77-2290-eb1d-ef3d677fe168",
        "name: "AlarmTemplate 1"
    }
]

RF Template

RF Templates are designed to make Radio Configs more consistent across Sites - by creating a RF Templates with desired settings and apply it to Sites. AP/Device-level overwrite can still be done.

NOTE: country_code, if specified, will take precedence over one defined in the Site

Get All Create RF Templates

GET /api/v1/orgs/:org_id/rftemplates
POST /api/v1/orgs/:org_id/rftemplates

Get / Update / Delete RF Templates

GET /api/v1/orgs/:org_id/rftemplates/:rftemplate_id
PUT /api/v1/orgs/:org_id/rftemplates/:rftemplate_id
DELETE /api/v1/orgs/:org_id/rftemplates/:rftemplate_id

Example

{
    "name": "5G-Restricted",
    "country_code": "US",
    "band_24": {
        "disabled": false,
        "channels": [ 1, 6, 11 ],
        "bandwidth": 20,
        "power": 16
    },
    "band_5": {
        "disabled": false,
        "channels": null,
        "bandwidth": 40,
        "power": 0,
        "preamble": "short",
        "power_min": 10,
        "power_max": 18
    },
    "band_6": {
        "disabled": false,
        "channels": null,
        "bandwidth": 40,
        "power": 0,
        "preamble": "short",
        "power_min": 10,
        "power_max": 18
    },
    "model_specific": {
        "AP61": {
            "band_5": {
                "disabled": false,
                "channels": [ 100, 104 ],
                "bandwidth": 40,
                "power": 0
            }
        }
    }
}

Response Definitions

Network Template

Network template is intended to be applied to a Site. It works like a blueprint of the network of the site.

All Site Settings can go into Network Templates. See Site:Site Setting for schema

Moreover, this can further be overwritten by individual Site Setting

Create Network Template

POST /api/v1/orgs/:org_id/networktemplates

Get / Update / Delete Network Templates

GET /api/v1/orgs/:org_id/networktemplates/:networktemplate_id
PUT /api/v1/orgs/:org_id/networktemplates/:networktemplate_id
DELETE /api/v1/orgs/:org_id/networktemplates/:networktemplate_id

Payload

{
    "name": "xxx",

    "networks": {
        // default is assumed, cannot be changed
        "default": {
            "vlan_id": 1
        },

        // create more
        "corp": {
            "vlan_id": 600
        },
        "guest": {
            "vlan_id": 700
        },
        "mgmt": {
            "vlan_id": 500
        }
    },


    // optional, the Org Networks that we'd like to import
    "import_org_networks": ["ap", "iot"],

    // mist_nac: enable mist_nac to use racsec
    "mist_nac": {
        "enabled": true,
        "network": "default"
    }

    "radius_config": {
        "auth_servers_timeout": 5,
        "auth_servers_retries": 3,
        "auth_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123"
            },
            {
                "host": "radius.internal",
                "port": 1812,
                "secret": "testing123"
            }
        ],
        "acct_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123"
            }
        ],
        "acct_interim_interval": 0,

        // Enable COA. Default is false. When coa_port is not specified, 3799 is the default value.
        “coa_enabled”: true,
        “coa_port”: 3799,

        // which network the RADIUS server resides, if there's static IP for this network,
        // we'd use it as source-ip
        "network": "default"

        // or specifiy "source_ip" directly
        "source_ip": "192.168.3.5"
    },

    "dns_servers": [ "8.8.8.8", "4.4.4.4" ],
    "dns_suffix": [ ".mist.local", ".mist.com" ],

    "port_usages": {
        "ap": {
            // the following parameter is assumed by default
            "mode": "trunk",
            "all_networks": true,
            "stp_edge": true,
            "port_network": "default",
            "mtu": 9192,

            // to limit networks it trunks
            "all_networks": false,
            "networks": [ "guest", "corp" ],

            // to change the native network
            "port_network": "mgmt"

            // to make the port disabled
            "disabled": true,

            // if alternative name is desired
            "description": "WAP"
        },
        "uplink": {
            // the following parameter is assumed by default
            "mode": "trunk",
            "all_networks": true,
            "stp_edge": false,
            "port_network": null,
            "enable_qos": false,
        },
        "iot": {
            // the following parameter is assumed by default
            "mode": "access",
            "stp_edge": true,
            "port_network": "default",

            // if DHCP snooping is enabled, DHCP server is allowed
            "allow_dhcpd": true,
        },
        "default": {
            // the following parameter is assumed by default and cannot be changed
            "mode": "access",
            "stp_edge": false,  // we don't know how it will be connected at default state, not doing anything
            "port_network": "default"
        },
        "disabled": {
            // mode to disable port
            // the following parameter is assumed by default
            "disabled": true,
        }
        "dynamic": {
            // this is a special mode where the actually usage is determined
            // by a set of rules
            // the port will start with `access` mode and isolated
            // depending on the rules, if resolved, the port will have
            // the resolved usage applied.
            //
            // if the port/link goes down, it goes back to the initial state
            "mode": "dynamic",

            // Control when the DPC port should be changed to the default port usage
            // Configuring to none will let the DPC port keep at the current port usage.
            // The default value is link_down
            "reset_default_when": "none",   // none or link_down.

            "rules": [
                // use LLDP attributes
                {
                    "src": "lldp_system_name",  // or lldp_chassis_id
                    "expression": "[0:3]",           // "abcdef" -> "abc"
                                  "split(.)[1]",     // "a.b.c" -> "b"
                                  "split(-)[1][0:3], // "a1234-b5678-c90" -> "b56"
                    "equals": "SENSOR",
                    "usage": "iot"
                },
                // use equals_any to match any item in a list
                {
                    "src": "lldp_chassis_id",
                    "expression": "[0:17]",
                    “equals_any”: [“00:11:22:33:44:55", “00:11:22:33:44:66”, “00:11:22:33:44:77"],
                    "usage": "iot"
                },
                // use RADIUS (WIP)
                {
                    "src": "radius_username",  // or radius_group
                    "expression": "[0:3]",           // "abcdef" -> "abc"
                                  "split(.)[1]",     // "a.b.c" -> "b"
                                  "split(-)[1][0:3], // "a1234-b5678-c90" -> "b56"
                    "equals": "SENSOR"
                    "usage": "iot"
                },
            ]
        },

        // additional usages can be defined
        "user": {
            "mode": "access",
            "stp_edge": true,

            // 802.1x
            "port_auth": "dot1x",
            "enable_mac_auth": false,
            "mac_auth_protocol": "eap-md5", // eap-md5 (default) / pap / eap-peap. This type is ignored if mist_nac is enabled.  
            "guest_network": null,
            "bypass_auth_when_server_down": false,
        },
    },

    "group_tags": {

    },

    "switch_matching": {
        "enable": true,

        "rules": [
            {
                "name": "match by name",
                "match_name[0:3]": "abc",
                "match_model": "EX4300",

                "port_config": {
                    "ge-0/0/0": {
                        "usage": "uplink"
                    },
                    "ge-0/0/8-16,ge-1/0/0-47": {
                        "usage": "ap"
                    },

                    // this is assumed
                    "*": {
                        "usage": "default"
                    }
                },

                // additional CLI commands to append if this rule matches
                // NOTE: no check is done
                "additional_config_cmds": [
                    "set snmp community public"
                ],
                "port_mirroring": {
                    "port_mirror": {
                        "input_port_ids_ingress": ["ge-0/0/4"],
                        "input_networks_ingress": ["test"],
                        "input_port_ids_egress": ["ge-0/0/5", "ge-0/0/6"],
                        "output_port_id": "ge-0/0/3",
                    },
                    "port_mirror_test": {
                        "input_port_ids_ingress": ["ge-0/0/3"],
                        "input_networks_ingress": ["iot"],
                        "input_port_ids_egress": ["ge-0/0/22", "ge-0/0/21"],
                        "output_port_id": "ge-0/0/4",
                    },
                    "port_mirror_test_2": {
                        "ingress_port_ids": ["ge-0/0/11"],
                        "egress_port_ids": ["ge-0/0/12"],
                        "output_ip_address": "1.2.3.4",
                    }
                },
                "stp_config": {
                    "bridge_priority": "8k"
                },

                "switch_mgmt": {
                    "config_revert_timer": 5,
                    // Enable to provide the FQDN with DHCP option 81. Default is false
                    "dhcp_option_fqdn": false

                    // use mxedge as proxy
                    "use_mxedge_proxy": true,
                    "mxedge_proxy_host": "1.1.1.1",
                    "mxedge_proxy_port": 2222,  // optional, default is 2222
                    "ap_affinity_threshold": 10,
                    "cli_idle_timeout": 20,
                    "cli_banner": "\t\tW A R N I N G !!!!!!!",
                    "local_accounts": {
                        "user1": {
                            "role": "admin", // none (default) / admin / read / helpdesk
                            "password": "Juniper123" // optional
                        },
                    },
                    "fips_enabled": true // default is false
                }
            },
            {
                "name": "match by role",
                "match_role": "access",

                "port_config": {
                    "ge-0/0/0": {
                        "usage": "uplink"
                    }
                },

                // additional CLI commands to append if this rule matches
                // NOTE: no check is done
                "additional_config_cmds": [
                    "set snmp community public2"
                ]
            },
            {
                "name": "access-no-out-of-band",
                "match_role": "access",
                "match_model[0:6]": "EX2300"
                "switch_mgmt": {
                    "disable_oob_down_alarm": true
                }
            }
        ]
    },

    "optic_port_config": {
        "et-0/0/0": {
            "speed": "25g",
            "channelized": True // enable channelization 
        }
        "et-0/0/1": {
            "speed": "25g" // do chassis speed by default
        }
    }

    "snmp_config":{
        "enabled": true, // enable or disable
        "name": "TGH-1K-QFX10K",
        "location": "Las Vegas, NV",
        "description": "Juniper QFX Series Switch - 1K_5LA",
        "contact": "cns@juniper.net",
        "network": "default",
        "client_list": [
            {
                "client_list_name": "clist-1",
                "clients": [
                    "151.140.101.218/32",
                    "151.140.2.179/32"
                ]
            }
        ],
        "views":[
            {
                 "view_name":"all",
                 "oid": "1.3.6.1",
                 "include": true  //oid 1.3.6.1 include"
            }
        ],
        "engine_id_type": "local", // local (default) / use_mac_address
        "engine_id": "engine-id-suffix", // if engine_id_type is local, this is the suffix to use
        "trap_groups": [
            {
                "group_name": "profiler",
                // Categories list can refer to https://www.juniper.net/documentation/software/topics/task/configuration/snmp-trap-groups-configuring-junos-nm.html
                "categories": [
                    "link", "authentication"
                ],
                "targets": [
                    "172.29.158.19",
                    "172.29.146.73"
                ],
                //version can be v1, v2 and all
                "version": "v2"
            }
        ],
        "v2c_config": [
            {
                "community_name": "abc123",
                "authorization": "read-only",
                "view": "all" //view name here should be defined in views above
            },
            {
                "community_name": "abc1233",
                //client_list_name here should refer to client_list above
                "client_list_name": "clist-1"
            }
        ],
        "v3_config": {
            "usm": [
                {
                    "engine_type": "remote_engine | local_engine",
                    "remote_engine_id": "00:00:00:0b:00:00:70:10:6f:08:b6:3f <remote engine required only>",
                    "users": [
                        {
                            "name": "m01620",
                            "authentication_type": "authentication-md5 | authentication-sha | authentication-sha224 | authentication-sha256 | authentication-sha384 | authentication-sha512 | authentication-none", //sha224, sha256, sha384, sha512 are supported in 21.1 and newer release
                            "authentication_password": "at least eight characters long, include alphabetic, numeric, and special characters, but it cannot include control characters. <Don't require if type is none>",
                            "encryption_type": "privacy-aes128 | privacy-des | privacy-3des | privacy-none",
                            "encryption_password": "at least eight characters long, include alphabetic, numeric, and special characters, but it cannot include control characters. <Don't require if type is none>",
                        }
                    ]
                }
            ],
            "vacm": {
                "access": [
                    {
                        "group_name": "group_name",
                        "prefix_list": [
                            {
                                "type": "default_context_prefix | context_prefix",
                                "context_prefix": "iil <needed only type is context_prefix>",
                                "security_model": "any | usm | v1 | v2c",
                                "security_level": "privacy | authentication | none",
                                "notify_view": "all <refer to above view name>",
                                "read_view": "all <refer to above view name>",
                                "write_view": "all <refer to above view name>"
                            }
                        ]
                    }
                ],
                "security_to_group": {
                    "security_model": "usm | v1 | v2c",
                    "content":[
                        {
                            "security_name": "security_name",
                            "group": "group_name, <refer to above group_name under access>"
                        }
                    ]
                }
            },
            "notify": [
                {
                    "name": "notify_name",
                    "tag": "tag_name",
                    "type": "trap | inform"
                }
            ],
            "notify_filter": [
                {
                    "profile_name": "notify_name",
                    "contents": [
                        {
                            "oid": "1.3.6.1.4.1",
                            "include": true  //oid object-identifier (include | exclude)
                        }
                    ]
                }
            ],
            "target_parameters": [
                {
                    "name": "target_parameters_name",
                    "notify_filter": "profile_name <refer to profile-name in notify-filter above>",
                    "message_processing_model": "v1 | v2c | v3",
                    "security_level": "authentication | none | privacy",
                    "security_model": "usm | v1 | v2c",
                    "security_name": "m01620 <refer to security_name in usm>"
                }
            ],
            "target_address": [
                {
                    "target_address_name": "target_address_name",
                    "address": "address",
                    "address_mask": "address_mask",
                    "port": 161,
                    "tag_list": "tag name <refer to notify tag above, can be multiple with blank>",
                    "target_parameters": "target_parameters <refer to notify target parameters name above>"
                }
            ]
        }
    }
}

AP Template

Get / Update / Delete AP-Port Templates

GET /api/v1/orgs/:org_id/aptemplates/:aptemplate_id
PUT /api/v1/orgs/:org_id/aptemplates/:aptemplate_id
DELETE /api/v1/orgs/:org_id/aptemplates/:aptemplate_id

Example

{
    "ap_matching": {
        "enabled": true,

        "rules": [
            {
                "name": "AP12",
                "match_model": "AP12",

                "port_config": {
                    "eth1,eth2": {
                        // see Device Config's port_config
                    }
                }
            },
        }
    },
    "wifi": {
        "enabled": true,
        "mesh_enabled": true,
        "mesh_allow_dfs": false,
        "mesh_enable_crm": false
        "cisco_enabled": true,
        "proxy_arp": "default",
        "enable_arp_spoof_check": false,
        "locate_connected": false,
        "locate_unconnected": false,
        "enable_shared_radio_scanning": false,
        "disable_11k": false,
        "disable_radios_when_power_constrained": false,
    },
}

Site Template

Site template is intended to be applied to a Site. The items in site setting which should be shared for all device types.

Create Network Template

POST /api/v1/orgs/:org_id/sitetemplates

Get / Update / Delete Site Templates

GET /api/v1/orgs/:org_id/sitetemplates/:sitetemplate_id
PUT /api/v1/orgs/:org_id/sitetemplates/:sitetemplate_id
DELETE /api/v1/orgs/:org_id/sitetemplates/:sitetemplate_id

Example

{
    "name": "template_000",
    "vars": {
        "VLAN_ID': "2345",
        "SSID_STR': "mist"
    },
    "auto_upgrade": {
        "enabled": true,
        "version": "stable",
        "time_of_day": "01:00",
        "day_of_week": "mon"
    }
}

Device Config Generation

Mist provides many ways (device-type specific template, site template, device profile, per-device) to configure devices for different kind of scenarios.

The precedence goes from most specific to least specific

Device > Device Profile > RFTemplate (for AP only) > DeviceType-specific Template > Site Template > Site Setting

EVPN

In some scenarios, you may want to have EVPN topologies across sites. For usage, seesee Site:EVPN

GET /api/v1/orgs/:org_id/evpn_topologies
POST /api/v1/orgs/:org_id/evpn_topologies

GET /api/v1/orgs/:org_id/evpn_topologies/:evpn_topology_id
PUT /api/v1/orgs/:org_id/evpn_topologies/:evpn_topology_id
DELETE /api/v1/orgs/:org_id/evpn_topologies/:evpn_topology_id

Networks

Networks are usually subnets that have cross-site significance. They will got merged into networks in and Site Setting For gateways, they can be used to define Service Routes.

Create Network

POST /api/v1/orgs/:org_id/networks

Get / Update / Delete Network

GET /api/v1/orgs/:org_id/networks/:network_id
PUT /api/v1/orgs/:org_id/networks/:network_id
DELETE /api/v1/orgs/:org_id/networks/:network_id

{
    "name": "store",
    "vlan_id": 70,
    "subnet": "192.168.70.0/24",
    "gateway": "192.168.70.1",
    "subnet6": "fdad:b0bc:f29e::/32",
    "gateway6": "fdad:b0bc:f29e::1",


    // whether to allow clients in the network to talk to each other
    "isolation": false,

    // whether to disallow Mist Devices in the network
    "disallow_mist_services": false,  // default is false

    // for a Network (usually LAN), it can be routable to other networks (e.g. OSPF)
    "routed_for_networks": ["pos"], 

    // whether this network has direct internet access
    "internet_access": {
        "static_nat": {
            "63.16.0.1": {"internal_ip": "192.168.70.3", "name": "printer-1"},
            "63.16.0.32/30": {"internal_ip": "192.168.70.16/30", "name": "pos-stations"},
        },
        "destination_nat": {
            ":2222": {"internal_ip": "192.168.70.30", "name": "ssh", "port": 22},
            "63.16.0.3:443": {"internal_ip": "192.168.70.5", "name": "web server", "port": 443}
        },

        // a quick way to enable this network to access Internet
        "create_simple_service_policy": false   // default is false
    },

    // whether this network can be accessed from vpn
    "vpn_access": {
        "data-center": {
            "routed": true,  // whether this network is routable
            "allow_ping": false,  // whether to allow ping from vpn into this routed network

            // if routable = false (usually at Spoke), but some hosts needs to be reachable from Hub
            "nat_pool": "172.16.0.0/26",  // a subnet is required to create and advertise the route to Hub
            "source_nat": {
                "external_ip": "172.16.0.8/30"
            },
            "static_nat": {
                "172.16.0.1": {"internal_ip": 192.168.70.3", "name": "pos-station-1"},
                "172.16.0.2": {"internal_ip": 192.168.70.8", "name": "pos-station-2"}
                "172.16.0.12/30": {"internal_ip": 192.168.70.12/30", "name": "pos-stations"}
            },
            "destination_nat": {
                "172.16.0.5/30": {"internal_ip": "192.168.70.5/30", "name": "web server"}
                "172.16.0.3:8443": {"internal_ip": "192.168.70.5", "name": "web server", "port": 443}
            },

            // if routed=true, whether to advertise an aggregated subnet toward HUB
            // this is useful when there are multiple networks on SPOKE's side
            "advertised_subnet": "172.16.0.0/24",

            // optionally, how HUB should deal with routes it received from Spokes
            // 1. toward overlay            
            "no_readvertise_to_overlay": false,
            "summarized_subnet": "172.16.0.0/16",
            // by default, the routes are only readvertised toward the same vrf on spoke
            // to allow it to be leaked to other vrfs
            "other_vrfs": [ "iot" ],

            // 2. toward LAN-side BGP peers
            "no_readvertise_to_lan_bgp": false, 
            "summarized_subnet_to_lan_bgp": "172.16.0.0/16"

            // 2. toward LAN-side OSPF peers
            "no_readvertise_to_lan_ospf": false,
            "summarized_subnet_to_lan_ospf": "172.16.0.0/16"
        }
    },

    // whether to enable multicast support (only PIM-sparse mode is supported)
    "multicast": {
        "enabled": true,  // default is false

        // group address to RP (rendezvous point) mapping
        "groups": {
            "225.1.0.3/32": {
                "rp_ip": "10.10.0.5"
            }
        }

        // if the network will only be the soruce of the multicast traffic, IGMP can be disabled
        "disable_igmp": false  // default is false
    },

    "tenants": {
        "pos-stations": {
            "addresses": ["192.168.70.16/30"]
        },
        "printer-1": {
            "addresses": ["192.168.70.3"]
        },
    }
}

Services

Base URI

/api/v1/orgs/:org_id/services

Example

{
    "name": "dc_service",
    "description": "optional",

    "type": "custom",  // custom (default) / apps / app_categories

    // when type = custom, ip subnet
    "addresses": ["10.0.0.0/8", "172.21.0.0/16", "2001:db8:abcd:12::/64", "fd28::/128"],  // the subnets where the service resides (if more specific is required)
    "specs": [
        {
            "protocol": "tcp",  // tcp / udp / icmp / gre / any / ":protocol_number", `protocol_number` is between 1-254, default is `any`
            "port_range": "80"  // or
        }
    ],

    // when type = custom, web filtering
    "hostnames": ["example.com", "*.google.com"],  // the hostnames
    // specs is optional, if it doesn't exist, http and https is assumed. If non-standard http/https ports are used
    "specs": [
        {
            "protocol": "tcp",
            "port_range": "8080,8443"
        }
    ],

    // when type = apps
    "name": "allowed_apps",
    "apps": [ "office365", "okta"],  // list of applications are available through
                                            /const/applications,
                                            /insight/top-app-by-bytes?wired=true or
                                            /const/gateway_applications

    // when type = app_categories
    "name": "allowed_app_categories",
    "app_categories": [ "Sports"],  // list of application categories are available through /const/app_categories
    "app_subcategories": [ "Shopping" ], // list of application sub-categories are available through /const/app_subcategories

    // when type = urls
    "type": "urls",
    "urls": ["http://example.com", "*.google.com"], // no need for spec as URL can encode the ports being used.

    // when type=apps, we'll choose traffic_type automatically
    // when type=addresses/hostnames, you can provide your own settings, also optionally,
    "traffic_type": "data_best_effort",  // data_best_effort (default) / ... (from /const/traffic_types) / custom

    // when traffic_type is `custom`
    "failover_policy": "revertable",  // revertable (default) / non_revertable / none
    "traffic_class": "best_effort",  // best_effort (default) / high  / medium / low
    "dscp": 46,
    "max_latency": 100,
    "max_jitter": 30,
    "max_loss": 1,
    "ssr_relaxed_tcp_state_enforcement": true,  // default is false

    // bandwidth limiting - SSR only
    "service_limit_up": 300000,  // 0-107374182, optional, default is unlimited, in kbps
    "service_limit_down": null,  // 0-107374182, optional, default is unlimited, in kbps
    "client_limit_up": 300000,  // 0-107374182, optional, default is unlimited, in kbps
    "client_limit_down": 100000,  // 0-107374182, optional, default is unlimited, in kbps
}

VPN

VPN object represents an overlay network where gateways can participate in and optionally expose routes to.

Base URI

/api/v1/orgs/:org_id/vpns

Payload

{
    // type = hub_spoke (default)
    "name": "data-center",
    "type": "hub_spoke",

    "paths": {
        "dc1-broadband": {
        },
        "dc1-mpls": {
        },
        "dc2-broadband": {
        },

        "dc2-pod2-broadband": {
            "pod": 2   // default is 1, 1-128
        }
    },    
    "path_selection": {
        "strategy": "disabled",  // disabled (default) / simple / manual
    },

    // type = mesh
    "name": "mesh-useast",
    "type": "mesh",
    "paths": {
        // the path offered
        “wan0": {
            “peer_paths”: {
                // preference indicates which outgoing wan should be preferred
                “wan0”: { “preference”: 2 }
                “wan1”: { “preference”: 1 }
            },

            // behavior of this mesh path
            "bfd_profile": "lte",  // broadband (default) / lte
            "bfd_use_tunnel_mode": true,  // false (default), whether to use tunnel mode. SSR only
            "traffic_shaping": {
                 "enabled": true,
                 "max_tx_kbps": 3000,  // 3Mbps
                 // percentages for differet class of traffic: high / medium / low / best-effort
                 // adding up to 100 
                 "class_percentages": [ 80, 10, 9, 1 ]  // default is [80, 10, 9, 1 ]
            }
        },
        “wan1”: {
            “peer_paths”: {
                 “wan1”: { “preference”: 2 }
            }
        },
        “mpls”: {
            “peer_paths”: {
                 “mpls”: { “preference”: 1 }
            }
        }
    }
    /*
        gateways participating will

        // 1. defines which WAN port will join a mesh and how (meshlink_name)
        "port_config": {
            "ge-0/0/0": {
                "usage": "wan",
                "name": "wan0",
                ...
                "vpn_paths": {
                    "wan0.mesh-useast": {
                        "role": "mesh"  // assumed
                    },
                    ...
                },
            }
        }

        // 2. path preference
        “path_preference”: {
            “to_mesh”: {
                “strategy”: “ordered”,  // ordered (default) / weighted / ecmp
                “paths”: [
                    {
                        “type”: “vpn”,
                        “name”: “wan0.mesh1”
                    },
                    // ... path by hub-spoke-vpn or wan ...
                ]
             }
        }            
    */
}

Service Policies

Base URI

/api/v1/orgs/:org_id/servicepolicies

Payload

{
    "name": "DC-APPs",
    "tenants": ["pos.store", "camera.store"],
    "services": ["dc-apps"],
    "action": "allow", // allow (default) / deny
}

IDP Profiles

Base URI

/api/v1/orgs/:org_id/idpprofiles

Payload

{
    "name": "relaxed",

    "base_profile": "strict",  // strict (default) / standard
    // overwrites takes precedence over the base_profile
    "overwrites": [
        {
            "matching": {
                "severity": [ "major" ],  // critical / major / minor / info
                "attack_name": [ "HTTP:INVALID:HDR-FIELD" ]
                "dst_subnet": [ "63.1.2.0/24" ],
            },
            "action": "alert",  // alert (default) / drop (siliently dropping packets) / close (notify client/server to close connection)
        }
    ]            
}

Antivirus Profile

Base URI

/api/v1/orgs/:org_id/avprofiles

Payload

{
    "name": "av-custom",
    "url_whitelist": [],
    "mime_whitelist": [],
    "fallback_action": "permit", // permit / block
    "max_filesize": 10000 // 20-40000 (KB)
    "protocols": [] // ftp / http / imap / pop3 / smtp
}

Advance Anti Malware Profile (SkyAtp)

Base URI

/api/v1/orgs/:org_id/aamwprofiles

Payload

{
    "name": "aamw-custom",
    // sky atp file scanning parameters
    "categories": [{
        "category": "executable" // archive / document / pdf / executable / rich_application / library / os_package / mobile / java / configuration / script
        "hash_lookup_only": false, // default false, false / true
    }]
    "verdict_threshold": 8,  // default 8, minimum: 1, maximum: 10
    "file_action": "block", // default block, block / permit
    "fallback_action": "block", // default block/ permit / block 
}

Sky ATP Secintel Profile

Base URI

/api/v1/orgs/:org_id/secintelprofiles

Payload

{
    "name": "secintel-custom",
    "profiles": [{"category": "CC", // CC / IH (Infected host) / DNS
                  "action": "default" // default / standard / strict
                }]
}

Gateway Template

Gateway Template is applied to a site for gateway(s) in a site.

Create Gateway Template

POST /api/v1/orgs/:org_id/gatewaytemplates

Get / Update / Delete Gateway Templates

GET /api/v1/orgs/:org_id/gatewaytemplates/:gatewaytemplate_id
PUT /api/v1/orgs/:org_id/gatewaytemplates/:gatewaytemplate_id
DELETE /api/v1/orgs/:org_id/gatewaytemplates/:gatewaytemplate_id

Payload

{
    "name": "xxx",

    "type": "standalone",  // standalone (default) / spoke / hub

    "networks": {
        // additional networks that are not already defined from Networks
    },

    "port_config": {
        // WAN
        "ge-0/0/0": {
            "usage": "wan",
            "name": "wan0",
            "critical": false, // default is false, if want to generate port up/down alarm, set it to true
            "wan_disable_speedtest": false, // default is false.  to disallow marvis/ scheduler to run speedtest on this port, set it to true
            "description": "towards ISP”,

            "wan_type": "broadband",  // broadband (default), dsl, lte
            "ip_config": {
                "type": "dhcp",  // dhcp (default) / static / pppoe

                // if type=pppoe
                "pppoe_auth": "none",  // none (default) / chap / pap
                "pppoe_username": "u13534",
                "pppoe_password": "foryoureyesonly",

                // for ipv6
                "type6": "static", // autoconf (default) / dhcp / static
                "ip6": "2601:1700:43c0:dc0:20c:29ff:fea7:93bc",
                "netmask6": "/64",
                "gateway6": "2601:1700:43c0:dc0::1",
            },
            // optional, if spoke should reach this port by a different IP
            "wan_ext_ip": "64.2.4.3",
            "wan_ext_ip6": "2601:1700:43c0:dc0::10",
            // optional, by default, source-NAT is performed on all WAN Ports using the interface-ip
            "wan_source_nat": {
                // if alternative nat_pool is desired
                "nat_pool": "64.2.4.0/30",
                "nat6_pool": "2601:1700:43c0:dc0:20c:29ff:fea7:93bc/126",
                // or to disable the source-nat
                "disabled": false  // default is false
            },

            "vpn_paths": {
                "dc1-broadband.data-center": {
                    "role": "spoke",  // spoke (default) / hub
                    "bfd_profile": "lte",  // broadband (default) / lte
                    "bfd_use_tunnel_mode": true,  // false (default), whether to use tunnel mode. SSR only
                    "traffic_shaping": {
                         "enabled": true,
                         "max_tx_kbps": 3000,  // 3Mbps
                         // percentages for differet class of traffic: high / medium / low / best-effort
                         // adding up to 100 
                         "class_percentages": [ 80, 10, 9, 1 ]  // default is [80, 10, 9, 1 ]
                    },

                    // for a given VPN, when path_selection.strategy=simple, the preference for a path (lower is preferred) 
                    "preference": 1
                },

                "wan0.mesh-useast": {
                    "role": "mesh"  // assumed
                    // all other configs (bfd_profile, bfd_use_tunnel_mode, ...) is defined in the VPN object
                }
            },

            // optionally, for WAN port, traffic_shaping can be performed
            "traffic_shaping": {
                "enabled": true,
                // percentages for differet class of traffic: high / medium / low / best-effort
                // adding up to 100 
                "class_percentages": [ 80, 10, 9, 1 ]  // default is [80, 10, 9, 1 ]
            },

            // for 128T
            "svr_port_range": "60000-60005",  // none (default), 1025 - 65535
            "ssr_no_virtual_mac": false,  // default is false, when SSR is running as VM, this is required on certain hosting platforms


            // other port settings
            "speed": "1g",  // auto (default)
            "duplex": "full",  // auto (default), full, and half
            "disable_autoneg": false,  // default is false
            "poe_disabled": true,  // default is false
            "mtu": null,  // default is null, between 552-1500 if specified
            "disabled": false, // default is false, port admin up (false) / down (false)
            // when wan_type = broadband
            "wan_arp_policer": "recommended" // default (system default) / recommended / max
            "wan_extra_routes": {
                "100.100.100.0/24": {
                    "via": "64.2.4.1"
                }
            },
            // for ipv6
            "wan_extra_routes6": {
                "2a02:1234:420a:10c9::/64": {
                    "via": "2a02:1234:200a::100"
                }
            },
            "wan_probe_override": {
                // when usage = wan
                "ips": [ "10.173.5.3" ],
                // for ipv6
                "ip6s": ["2001:4860:4860::8844"],
                "probe_profile": "broadband",  // broadband (default)/ lte
            },

            // if some networks are connected to this WAN port, it can be added here so policies can be defined
            "wan_networks": [ "ip-pool", "mpls-datacenter" ],
        },
        "cl-1/0/0": {
            "usage": "wan",
            "name": "lte",

            "wan_type": "lte",
            "lte_apn": "5ginternet",
            "lte_auth": "none",  // none (default) / chap / pap
            "lte_username": "user1",
            "lte_password": "pass",

            "ip_config": {
                "type": "dhcp"  // dhcp (default), static
            }
        },

        // DSL PPPoE (experimental)
        "at-1/0/0": {
            "usage": "wan",
            "name": "dsl",
            "wan_type": "dsl",
            "dsl_type": "adsl" // vdsl (default), adsl
            "dsl_vpi":  0 // 0 (default) 8 bit int
            "dsl_vci": 35 // 35 (default) 16 bit int
            "ip_config": {
                "type": "dhcp"  // dhcp (default), static
            }
        },

        // LAN
        "ge-0/0/1-5": {
            "usage": "lan",
            "networks": ["default", "guest", "pos"],

            // whether to preserve dscp when sending traffic over VPN (SSR-only)
            "preserve_dscp": true,

            "port_network": "default"
        },

        // if WAN interface is on a VLAN (e.g. an MPLS link through uplink switch/router)
        "ge-0/0/0.5": {  // name suffixed with ".<vlan_id>"
            "usage": "wan"
            "name": "mpls",
            "vlan_id": 5,
            "outer_vlan_id": null  // optional, for Q-in-Q

            "ip_config": {
                "type": "dhcp",  // dhcp (default), static
            }

            "vpn_paths": {
                "dc1-mpls.data-center": {
                    "role": "spoke"
                }
            },

            // "wan_type" will be ignored
            // "pci_address" will be ignored
        },
    },

    "oob_ip_config": {
        // out-of-band (vme/em0/fxp0) IP config
        // same payload as `ip_config` except dns / dns_suffix

        "vlan_id": xxx, // optional
        "use_mgmt_vrf": true, // true (default) / false

        // for host-out traffic (NTP/TACPLUS/RADIUS/SYSLOG/SNMP), if alternative source network/ip is desired, 
        "use_mgmt_vrf_for_host_out": false, // false (default), whether to use `mgmt_junos`

        // for HA Cluster, node1 can have different IP Config
        "node1": {
            // same payload as `ip_config` except dns / dns_suffix
            "vlan_id": xxx // optional, if different from parent
        }
    },

    // all the IP configs on the LAN side
    "ip_configs": {
        "guest": {
            "ip": "192.168.70.1",
            "netmask": "/24",
            // optional list of secondary IPs in CIDR format
            "secondary_ips": [ "192.168.50.1/24", "192.168.60.1/26"],
            "ip6": "2001:db8:abcd:12::1",
            "netmask6": "/64"
        },
    },

    "dhcpd_config": {
        "guest": {
            "type": "local",  // local (default) / relay / none
            "ip_start": "192.168.70.100",
            "ip_end": "192.168.70.200",
            "gateway": "192.168.70.1",

            // optional, system one will be used
            "dns_servers": [ "8.8.8.8", "4.4.4.4" ],
            "dns_suffix": [ ".mist.local", ".mist.com" ],

            // if using DHCP relay
            "type": "relay",
            "servers": ["11.2.3.4"]

            // if using DHCPv6 server
            "type6": "local" // none (default) / relay / local
            "ip6_start": "2607:f8b0:4005:808::2",
            "ip6_end": "2607:f8b0:4005:808::ff",

            // if using DHCPv6 relay
            "type6": "relay"
            "serversv6": ["2607:f8b0:4005:808::64"]
        }
    },

    "router_id": "10.2.1.10",  // auto-assigned if unset

    "path_preferences": {
        "dc_path": {
            "strategy": "ordered",  // ordered (default) / weighted / ecmp
            "paths": [
                {
                    "type": "vpn",
                    "name": "dc1-broadband.data-center",

                    // optional, spoke's outgoing wan is desired
                    "wan_name": "wan0",
                    // optional params depending on strategy
                    "cost": 10,

                    // SSR only
                    "disabled": false  // true if this specific path is undesired 
                },
                {
                    "type": "vpn",
                    "name": "dc1-mpls.data-center",
                },
                {
                    "type": "vpn",
                    "name": "dc2-broadband.data-center",
                }
            }
        },

        "to_spoke": {
            "strategy": "ordered",  // ordered (default) / weighted / ecmp
            "paths": [
                {
                    "type": "vpn",
                    "name": "dc1-broadband.data-center",

                    // optional, spoke's outgoing wan is desired
                    "wan_name": "wan0",                    
                    // SSR only
                    "disabled": true  // true if this specific path is undesired 
                }
            }
        },

        "local_path": {
            "strategy": "ecmp",  // ordered (default) / weighted / ecmp
            "paths": [
                {
                    "type": "wan",
                    "name": "wan0"
                },
                {
                    "type": "wan"
                    "name": "lte"
                },
                {
                    // use mpls path to dc1 as backup
                    "type": "vpn"
                    "name": "dc1-mpls.data-center",
                    // additionally, if this vpn path can be used for internet
                    "internet_access": true  // default is false
                }
            }
        },
        "local_breakout": {
            "paths": [
                {
                    "type": "tunnel",
                    "name": "zscalar"
                },
                {
                    "type": "wan",
                    "name": "wan0"
                },
            ]
        },

        "customized": {
            "paths": [
                {
                    // it can also be local
                    "type": "local",
                    "networks": ["guest"],

                    // optional, if a different gateway is desired
                    "gateway_ip": "192.168.30.5",
                    // optional, if destination IP is to be replaced
                    "target_ips": ["30.1.2.5"]
                }
            ]
        }
    },

    "tunnel_provider_options": {
        "jse": {
            // for jse-ipsec
            // this allow provisioning of adequate resource on JSE. Make sure adequate licenses are added
            "num_users": 5
            "org_name": "JSE_ORG1",  // optional
            "region": "auto",  // auto (default) / africa / asia / europe / north_america / south_america / oceania
        },

        "prisma": {
            // for prisma-ipsec
            "service_account_name": "sa1@1823425211",  // service account name to used for tunnel auto provisioning
        },

        "zscalar": {
            // for zscaler-ipsec and zscaler-gre        
            // see https://help.zscaler.com/zia/configuring-locations
            "use_xff": false,  // location uses proxy chaining to forward traffic

            "enforce_authentication": false,  // default is false

            // when enforce_authentication=false
            "enable_caution": false,  // display caution notification for non-authenticated users, default is false

            "enable_aup": false,  // display Acceptable Use Policy (AUP), default is false, use_xff has to be true
            "aup_acceptance_required": true,  // default is true 
            "aup_ssl_proxy": false,  // proxy HTTPs traffic, requiring Zscaler cert to be installed in browser, default is false  
            "aup_expire": 2,  // days before AUP is requested again, default is 1 day

            // optional
            "download_mbps": 200,  // the download bandwidth cap of the link, in Mbps
            "upload_mbps": 200,   // the download bandwidth cap of the link, in Mbps            

            // if use_xff == true 
            "sub_locations": [
                {
                    "name": "guest-wifi",
                    "subnets": ["172.16.8.0/24", "172.16.32.0/23"],
                    "enforce_authentication": false,  // default is false

                    // when enforce_authentication=false
                    "enable_caution": false,  // display caution notification for non-authenticated users, default is false

                    "enable_aup": false,  // display Acceptable Use Policy (AUP), default is false, use_xff has to be true
                    "aup_acceptance_required": true,  // default is true 
                    "aup_ssl_proxy": false,  // proxy HTTPs traffic, requiring Zscaler cert to be installed in browser, default is false  
                    "aup_expire": 2,  // days before AUP is requested again, default is 1 day

                    // optional
                    "download_mbps": 200,  // the download bandwidth cap of the link, in Mbps
                    "upload_mbps": 200,   // the download bandwidth cap of the link, in Mbps
                }                    
            ]
        },
    },


    "tunnel_configs": {
        "zscalar": {
            "provider": "zscaler-ipsec",

            // if provider = zscaler-ipsec
            "local_id": "{{ SITE_LOCAL_ID }}",
            "psk": "{{ SITE_PRESHARED_KEY }}",
            "primary": {
                "hosts": [ "63.1.5.3" ],
                "probe_ips": [ "1.1.1.1" ],
                "wan_names": [ "wan0", "wan1" ]
            },
            "secondary": {
                "hosts": [ "63.1.5.4" ],
                "probe_ips": [ "2.2.2.2" ],
                "wan_names": [ "wan1", "wan0" ]
            },

            // auto-provision (takes precedence)
            "auto_provision": {
                "enabled": true,
                "latlng": { "lat": 37.295833, "lng": -122.032946 },  // overwrite can be given
                "primary": {
                    "num_hosts": 2,

                    // optional, only needed if `vars_only`=false
                    "wan_names": ["wan0", "wan1"],
                },
                "secondary": null
            },

            "mode": "active-standby" // options are active-standby (default), active-active
        },
        "zscalar-gre": {
            "provider": "zscaler-gre",

            // if provider = zscaler-gre
            "primary": {
                "hosts": [ "216.66.5.49" ],
                "internal_ips": [ "172.18.58.121" ],
                "probe_ips": [ "172.18.58.122" ],
                "wan_names": [
                    "wan0",
                    "wan1"
                ]
            },
            "secondary": {
                "hosts": [ "199.168.149.179" ],
                "internal_ips": [ "172.18.58.125" ],
                "probe_ips": [ "172.18.58.126" ],
                "wan_names": [
                    "wan0",
                    "wan1"
                ]
            },
            "mode": "active-standby" // options are active-standby (default), active-active
        },
        "jse-ipsec": {
            "provider": "jse-ipsec",

            // if provider = jse-ipsec
            "local_id": "{{ SITE_LOCAL_ID }}",
            "psk": "{{ SITE_PRESHARED_KEY }}",
            "primary": {
                "hosts": [ "63.1.5.3" ],
                "probe_ips": [ "1.1.1.1" ],
                "remote_ids": ["abcd@juniper.net"],
                "wan_names": [ "wan0", "wan1" ]
            },
            "secondary": {
                "hosts": [ "63.1.5.4" ],
                "probe_ips": [ "2.2.2.2" ],
                "remote_ids": ["edfg@juniper.net"],
                "wan_names": [ "wan1", "wan0" ]
            },
            "mode": "active-standby" // options are active-standby (default), active-active,
        },
        "custom-ipsec": {
            "provider": "custom-ipsec",
            "protocol": "ipsec",

            "local_id": "{{ SITE_LOCAL_ID }}",
            "psk": "{{ SITE_PRESHARED_KEY }}",
            "local_subnets": ["1.0.0.0/24", "2.0.0.1/32"],   // Local protected subnet for policy-based IPSec negotiation
            "remote_subnets": ["5.0.0.0/24", "6.0.0.1/32"],  // Remote protected subnet for policy-based IPSec negotiation
            "primary": {
                "hosts": [ "63.1.5.3" ],
                "probe_ips": [ "1.1.1.1" ],
                "wan_names": [ "wan0" ]
            },
            "secondary": {
                "hosts": [ "63.1.5.4" ],
                "probe_ips": [ "2.2.2.2" ],
                "wan_names": [ "wan0" ]
            },
            "mode": "active-standby" // options are active-standby (default), active-active

            // customized ipsec parameters
            "version": "2", // 2 (default) / 1
            "ike_mode": "main", // main (default) / aggressive
            "ike_proposals": [
                {
                    "auth_algo": "sha2", // sha1, sha2, md5,
                    "enc_algo": "aes256", // 3des, aes128, aes256, aes_gcm256, aes_gcm128, null
                    "dh_group": "2" // 14 (default, 2048-bit) / 1 / 2 (1024-bit) / 5 / 15 (3072-bit) / 16 (4096-bit)
                                    // 19 (256-bit ECP) / 20 (384-bit ECP) / 21 (521-bit ECP) / 24 (2048-bit ECP)
                }
            ],
            "ike_lifetime": 3600,
            "ipsec_proposals": [
                {
                    "auth_algo": "sha2", // sha1, sha2, md5,
                    "enc_algo": "aes256", // 3des, aes128, aes256, aes_gcm256, aes_gcm128, null
                    "dh_group": "2"
                }
            ],
            "ipsec_lifetime": 1800,

            // networks reachable via this tunnel
            "networks": [ 
                "ntwk",
                "protected-net"
            ],

            "probe": {
                 "type": "icmp", // icmp (default) / http
                 "interval": 120, // how often to trigger the probe
                 "threshold": 3, // number of consecutive misses before declaring the tunnel down
                 "timeout": 20 // time within which to complete the connectivity check
            }
        },
        "custom-gre": {
            "provider": "custom-gre",
            "protocol": "gre",

            "primary": {
                "hosts": [ "216.66.5.49" ],
                "internal_ips": [ "172.18.58.121" ],
                "probe_ips": [ "172.18.58.122" ],
                "wan_names": [
                    "wan0",
                    "wan1"
                ]
            },
            "secondary": {
                "hosts": [ "199.168.149.179" ],
                "internal_ips": [ "172.18.58.125" ],
                "probe_ips": [ "172.18.58.126" ],
                "wan_names": [
                    "wan0",
                    "wan1"
                ]
            },
            "mode": "active-standby" // options are active-standby (default), active-active
        },
        "prisma-ipsec": {
            "provider": "prisma-ipsec",
            // networks reachable via this tunnel
            "networks": [
                "corp-network",
                "protected-network"
            ],
            "auto_provision": {
                "enabled": true,
                // by default, we'll use the location of the site to determine the optimal Remote Network location.

                // optionally, service_connection can be considered, then we'll also consider this along with the site location
                "service_connection": "Juniper-Lab-SC-1",    // Define service_connection if the traffic is to be routed to a specific service connection.
                                                             // This field takes a service connection name that is configured in the Prisma cloud, Prisma Access Setup -> Service Connections.

                // in the case user wants to override the auto discovery of remote network location and force the tunnel to use the specified peer location.
                "region": "us-west-1",  // auto(default) / us-west-1 / us-east-1 / eu-central-1 / ap-southeast-1 /..
                                        // https://docs.paloaltonetworks.com/prisma/prisma-access/3-0/prisma-access-panorama-admin/prepare-the-prisma-access-infrastructure/list-of-prisma-access-locations/list-of-locations-by-compute-location

                "primary": {
                    "probe_ips": [
                        "8.8.8.8"
                    ],
                    "wan_names": [
                        "wan0"
                     ]
                }
            }
        }
    },

    "idp_profiles": {
        "relaxed": {
            "base_profile": "strict",  // strict (default) / standard
            // overwrites takes precedence
            "overwrites": [
                {
                    "matching": {
                        "severity": [ "major" ],  // critical / major / minor / info
                        "attack_name": [ "HTTP:INVALID:HDR-FIELD" ]
                        "dst_subnet": [ "63.1.2.0/24" ],
                    },
                    "action": "alert",  // alert (default) / drop (siliently dropping packets) / close (notify client/server to close connection)
                }
            ]            
        }
    },

    // when a service policy denies a app_category, what message to show in user's browser
    "url_filtering_deny_msg": "Access to this URL Category has been blocked",

    "service_policies": [
        // policies for store
        {
            "name": "DC-APPs",
            "tenants": ["pos.store", "camera.store"],
            "services": ["dc-apps"],
            "action": "allow",
            "idp": {
                "enabled": true,  // default is false
                "idpprofile_id": "89b9d208-84a4-fa8f-af57-78f92c639cf2",  // org-level IDP Profile can be used, this takes precedence over `profile`
                "profile": "strict", // strict (default) / standard / or keys from from idp_profiles
                "alert_only": false                
            },
            // SRX-only
            "appqoe": {
                "enabled": true,  // default is false
            },
            // SRX-only
            "antivirus": {
                "enabled": true, // default is false
                "avprofile_id": "5cb2e071-cfc5-4231-b5f8-3543e04dfb55" // org-level AV Profile can be used, this takes precendence over 'profile'
                "profile": "default", // default / noftp / httponly / or keys from av_profiles
            },
            // SRX-only
            "secintel": {
                "enabled": True,
                "secintelprofile_id": "5cb2e071-cfc5-4231-b5f8-3543e04dfb55" // org-level secintel Profile can be used, this takes precendence over 'profile'
                "profile": "default", // default / standard / strict
            },
            // SRX-only
            "aamw": {
                "enabled": True,
                "aamwprofile_id": "5cb2e071-cfc5-4231-b5f8-3543e04dfb55" // org-level secintel Profile can be used, this takes precendence over 'profile'
                "profile": "standard", // standard / docsonly / executables
            },

            // by default, we derive all paths available and use them
            // optionally, you can customize by
            "path_preference": "dc_path",
            // SRX-only, optional
            "ssl_proxy": {
                "enabled": true,
                "ciphers_category": "strong" // strong(default), medium, weak
            }
        },
        {
            // we can use a policy defined at org level and overwrite some attributes
            "servicepolicy_id": "dbdf808a-5429-51b7-89ac-1b52d7a4b4b5",

            "name": "Cloud Apps",
            "tenants": ["pos.store", "camera.store"],
            "services": ["cloud-apps"],
            "path_preference": "local_path"
        },
        {
            "name": "Guest",
            "tenants": ["guest"],
            "service": ["internet"],
            "path_preference": "local_breakout"
        },
        {
            "name": "Mgmt from DC",
            "tenants": ["it.datacenter"],
            "services": ["store_servers"],
            "path_preference": "customized"
        },
        {
            "name": "local routing",
            "tenants": ["corp", "vendor"],
            "services": ["ping"],

            // access within the same VRF
            "local_routing": true
            // no path_preference
        },
        "syslog": {
            "enabled": False,
            "server_names": "dc_syslog_server"
        }
    ],

    "bgp_config": {
        "local": {
            "type": "internal",
            "networks": [ "corp" ],  // networks where we expect BGP neighbor to connect to/from
            "local_as": 65000,
            "auth_key": "auth-key",
            "export_policy": "export_policy",
            "import_policy": "import_policy",
            "neighbors": {
                "10.1.10.5": {
                    "disabled": false // Default false. If true, the BGP session to this neighbor will be administratively disabled/shutdown
                }
            },
            // by default, either inet/net6 unicast depending on neighbor IP family (v4 or v6)
            // for v6 neighbors, to exchange v4 nexthop, which allows dual-stack support, enable this
            "extended_v4_nexthop": true,            
        },
        "attlink": {
            "type": "external",
            "via": "wan",  // lan (default) / wan / tunnel
            // if via = wan
            "wan_name": "wan0",
            // if via = lan
            "networks": [ "corp" ],  // networks where we expect BGP neighbor to connect to/from
            // if via = tunnel
            "tunnel_name": "custom-ipsec",

            "local_as": 3000,
            "neighbor_as": 3105,
            "no_private_as": false // false(default) / true
            "auth_key": "auth-key",
            "disable_bfd": false,  // BFD provides faster path failure detection and is enabled by default
            "bfd_minimum_interval": 1-255000, by default, 1000 is used when type=external, 350 when type=internal
            "bfd_multiplier": 1-255, default is 3
            "hold_time":120, // 0-65535, default is 90s
            "graceful_restart_time":240 // 1-4095, default is 0 (disabled)
            "neighbors": {
                "63.1.56.3": {
                    // if per-neighbor as is desired
                    "neighbor_as": 500
                    "multihop_ttl": 64,  // 0-255, default is 0, assuming BGP neighbor is directly connected
                    "export_policy": "neighbor_specific_export_policy",
                    "import_policy": "neighbor_specific_import_policy",
                    "hold_time":120, // 0-65535, default is 90s
                    "disabled": false // Default false. If true, the BGP session to this neighbor will be administratively disabled/shutdown
                }
            },

            // by default, we'll re-advertise all learned BGP routers toward overlay
            "no_readvertise_to_overlay": false,

            // default export/import policies if no per-neighbor policies defined
            "export_policy": "export_policy",
            "import_policy": "import_policy"
        },
        "vpn1": {
            "via": "vpn",  //
            "vpn_name": "data-center",

            "import_policy": "import_policy",            
            "export_policy": "export_policy"            
        }
    }

    // routing-policies
    "routing_policies": {
        "sample_import_policy": {
            "terms": [
                {
                    // zero or more criteria/filter can be specified
                    // to match the term, all criteria have to be met
                    "matching": {
                        "prefix": ["192.168.0.0/16-30"],

                        "as_path": ["65001,65353"],
                        "protocol": ["direct"],  // direct / bgp / ospf / ...
                        "community": ["65001:2"],

                        // overlay-facing criteria (used for bgp_config where via=vpn)
                        "vpn_path": ["dc1-broadband"], // ordered list
                        "vpn_path_sla": {
                            "max_latency": 1500,
                            "max_loss": 30,
                            "max_jitter": null,
                        },
                        "vpn_neighbor_mac": ["7d027e0ffcb9"]
                    },

                    "actions": {
                        "accept": true,
                        "local_preference": "50", // optional, for an import policy, local_preference can be changed

                        // for SSR, hub decides how VRF routes are leaked on spole   
                        "add_target_vrfs": ["guest"]
                    }
                }
            ],
        },
        "sample_export_policy": {
            "terms": [
                {
                    "name": "export",
                    "matching": {
                        // zero or more criteria/filter can be specified
                        // to match the term, all criteria have to be met
                        "prefix": ["192.168.0.0/16-30"],

                        "as_path": ["65001", "65353"],  // takes regular expression
                        "protocol": ["direct"],  // direct / bgp / ospf / static / aggregate ...
                        "community": ["65001:2"],  // community
                        "route_exists": [{
                            "route": "192.168.0.0/24",
                            "vrf_name": "guest"  // name of the vrf instance, default is `default`
                                                 // it can also be the name of the VPN or wan if they
                        }]
                    },
                    "actions": {
                        "accept": true,
                        // when used as export policy, all optional
                        "community": [ "65003:10" ], // takes precedence
                        "add_community": [ "65003:10" ],
                        "exclude_community": [ "65003:10" ],
                        // by default, the local AS will be prepended, to change it
                        "prepend_as_path": ["65003"],
                        // exclude some as_path
                        "exclude_as_path": ["65002"],
                        // local preference
                        "local_preference": "30"
                    }
                }
            ],
        }
    },

    // static routes
    "extra_routes": {
        "it_mgmt": {   // use names from `networks`
            "via": "10.2.1.1"
        },
        "172.16.3.0/24": {
            "via": "10.2.1.1"
        }
    },
    // for ipv6
    "extra_routes6": {
        "2a02:1234:420a:10c9::/64": {
            "via": "2a02:1234:200a::100"
        }
    },
    // experimental
    "gateway_matching": {
        "enable": true,
        // see network template
    },

    // additional CLI commands to append
    // NOTE: no check is done
    "additional_config_cmds": [
        "set snmp community public2"
    ]
}

Port Usage

Configure HA

{
    "port_config": {
        "ge-0/0/5,ge-1/0/5": {
            "usage": "ha_control"
        },
        "ge-0/0/6,ge-1/0/6": {
            // for HA Data
            "usage": "ha_data"
        },
        "ge-0/0/0,ge-1/0/0": {
            "usage": "wan",
            "redundant": true,
            "reth_idx": 0,
            "reth_node": "node0"
        },
        "ge-0/0/2,ge-1/0/2": {
            "usage": "lan",
            "redundant": true,
            "reth_idx": 1,
            "reth_node": "node1",

            "networks": ["corp", "guest"],

            // SRX Only - support redundancy-group
            "redundant_group": 3, // 1-128 for physical SRX, 1-64 for virtual SRX (optional)
            // SSR only - supporting vlan-based redundancy (matching the size of `networks`)
            "reth_nodes": ["node1", "node0"]
        },
    }
}

Generate Default Gateway Config

GET /api/v1/const/default_gateway_config?model=SRX320&ha=false

Parameters

Response

{
    "port_config": {
        "ge-0/0/0,ge-0/0/7": {
            "usage": "wan",
            "name": "wan",
            "ip_config": {
                "type": "dhcp"
            }
        },
        "ge-0/0/1-6": {
            "usage": "lan",
            "port_network": "lan"
        },
        "cl-1/0/0": {
            "usage": "wan",
            "name": "lte",
            "wan_type": "lte",
            "ip_config": {
                "type": "dhcp"
            }
        }
    },
    "networks": {
        "lan": {
            "name": "lan",
            "vlan_id": 1,
            "subnet": "192.168.1.0/24"
        }
    },
    "ip_configs": {
        "lan": {
            "type": "static",
            "ip": "192.168.1.1"
        }
    },
    "dhcpd_config": {
        "lan": {
            "ip_start": "192.168.1.2",
            "ip_end": "192.168.1.254"
        }
    },
    "path_preferences": {
        "wan": {
            "paths": [
                {
                    "type": "wan",
                    "name": "wan"
                }
            ]
        }
    },
    "service_policies": [
        {
            "name": "Internet",
            "tenants": [
                "lan"
            ],
            "services": [
                "any"
            ],
            "action": "allow",
            "path_preference": "wan"
        }
    ]
}

Device Replacement

It’s a common request we get from the customers. When a AP HW has problem and need a replacement, they would want to copy the existing attributes (Device Config) of this old AP to the new one. It can be done by providing the MAC of a device that’s currently in the inventory but not assigned. The Device replaced will become unassigned. This API also supports replacement of Mist Edges. This API copies device agnostic attributes from old Mist edge to new one. Mist manufactured Mist Edges will be reset to factory settings but will still be in Inventory.Brownfield or VM’s will be deleted from Inventory.

POST /api/v1/orgs/:org_id/inventory/replace

Request

{
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "mac": "5c5b35000101",
    "inventory_mac": "5c5b35000301",
    "discard": []
    // tunterm_port_config is optional and applicable for mist-edge replacement only
    "tunterm_port_config": {"separate_upstream_downstream": true/false,
                            "upstream_ports": ["0", "1"],
                            "downstream_ports": ["2", "3"]
                            }
}

Parameters

NOTE

For Gateway devices only like-for-like replacements (can only replace a SRX320 with a SRX320 and not some otehr model) are allowed.

Get Org Devices

GET /api/v1/orgs/:org_id/devices

{
    "results": [
        {
            "mac": "5c5b350eb31b",
            "name": "Conference Room"
        }
    ]
}

Template

Templates are collection of configs that can be applied to orgs / sitegroups / sites

Why Templates?

Conceptually, site is where configurations will be created (and eventually be derived). People with only a few deployments (or when each deployment is different) will mostly define their WLAN/Tunnels/Policies under a site.

For big deployments (hundreds / thousands of sites), it’s unpractical to do so. Instead, they can define templates (holding same set of stuff WLAN/Tunnels/Policies) and apply them to sites. Therefore,

1. these WLANs/Tunnels/Policies are contained in the template. I.e. Objects like WLAN / WxlanTunnel / WxlanRule can only reference each other in the same template
2. At the site level, one site may be applied with multiple templates as well as holding its own.

So how does derivation work?

For WLANs, it’s straightforward, a site will simply have multiple WLANs from multiple templates plus those defined in a site itself For Wxlan, all template Wxlan Rules will be checked first. If there’s no match, it will continue checking the Site Wxlan Rules. If there’s no match, the default action defined in the Site Wxlan Rule will be used.

However, a template Wxlan Rule differs from a Site Wxlan Rule in two ways.

1. It has to come with a WLAN Label on the left. If not, it’s implicit that it matches with ANY of the WLANs defined in the template
2. AP Wxlan Tag (match=ap_id) cannot be created / used as there’s no AP concept at org level

Get All Create Templates

GET /api/v1/orgs/:org_id/templates
POST /api/v1/orgs/:org_id/templates

Get Update Delete Templates

GET /api/v1/orgs/:org_id/templates/:template_id
PUT /api/v1/orgs/:org_id/templates/:template_id
DELETE /api/v1/orgs/:org_id/templates/:template_id

Example

{
    "name": "west",
    "applies": {
        "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
        "sitegroup_ids": [ "581328b6-e382-f54e-c9dc-999983183a34", "f57096b9-0c2f-4df6-c77b-ae6ae87a3d43" ],
        "site_ids": [ "4ac1dcf4-9d8b-7211-65c4-057819f0862b" ]
    },
    "exceptions": {
        "sitegroup_ids": [ "90badd2e-c028-5e8e-dd8f-b3c718882b9d" ],
        "site_ids": [ "52f4347e-3e4b-186c-21ca-ad5b70eb23d6" ]
    },
    "filter_by_deviceprofile": true,
    "deviceprofile_ids": [
        "6f4bf402-45f9-2a56-6c8b-7f83d3bc98e9",
    ]
}

Definition

Clone Template

POST /api/v1/orgs/:org_id/templates/:template_id/clone

Request

{
    "name": "Cloned"
}

Org Wlan

Base URI

/api/v1/orgs/:org_id/wlans

Example

see Site:Wlan for schema

{
    "name": "whatever",
    "template_id": "867860f2-dd82-3677-54a5-4d6b139c96ca"
    ...
}

Wlan Portal Image Upload

Upload background image for Portal

POST /api/v1/orgs/:org_id/wlans/:wlan_id/portal_image

see Site:Wlan Portal Image Upload for schema

Wlan Portal Image Delete

Delete background image for Portal

DELETE /api/v1/orgs/:org_id/wlans/:wlan_id/portal_image

see Site:Wlan Portal Image Delete

Org Wxlan Tunnel

/api/v1/orgs/:org_id/wxtunnels

There can be Management Tunnels (which can be applied to a sitegroup, see Org:Setting) as well as Data Tunnels, which can only be applied to Org Wlans in a Template. Moreover, the WxlanTunnel inside a template can only be used by Org Wlans in the same template

see Site:Wlan Tunnels for schema

Org Wxlan Tags

Wxlan Tags can be defined inside a template. When used, it can be deployed to

/api/v1/orgs/:org_id/wxtags

see Site:Wlan Tags for schema

Org Wxlan Rules

Wxlan Rules can be applied to template. WxlanRule defined inside a template will operate with the scope of specified template.

/api/v1/orgs/:org_id/wxrules

see Site:Wlan Rules for schema

Org Asset Filters

/api/v1/orgs/:org_id/assetfilters

see Site:Asset Filters for schema

Org Asset

/api/v1/orgs/:org_id/asset
/api/v1/orgs/:org_id/asset/:asset_id

see Site:Asset for schema

Org Import Assets

POST /api/v1/orgs/:org_id/assets/import

see Site:Asset for schema

Org Assets Status

GET /api/v1/orgs/:org_id/stats/assets
GET /api/vi/orgs/:org_id/stats/assets/:asset_id

Response

see Site:Asset:Stats for schema

Org Assets Search

GET /api/v1/orgs/:org_id/stats/assets/search
GET /api/v1/orgs/:org_id/stats/assets/search?mac='fbc721cc3022'

Parameters

Response

{
    "results": [
        {
            "battery_voltage": "283",
            "eddystone_uid_namespace": "f7826da6bc5b71e0893e",
            "last_seen": 1633971808,
            "eddystone_uid_instance": "424c43527039",
            "eddystone_url": "eddystone_url",
            "mac": "fbc721cc3022",
            "manufacture": "Unknown",
            "timestamp": 1633971808667,
            "map_id": "map_id",
            "org_id": "org_id",
            "by": "assetfilter",
            "site_id": "site_id",
            "name": "name",
            "temperature": "0.0"
        },
    ],
    "start": 1633367108.3799882,
    "end": 1633971908.3799632,
    "limit": 100,
    "total": 1
}

Count Org Asset by distinct field

GET /api/v1/orgs/:org_id/stats/assets/count
GET /api/v1/orgs/:org_id/stats/assets/count?distinct=ibeacon_uuid

Parameters

Response

{
    "results": [
        {
            "site_id": "site_id",
            "count": 19
        }
    ],
    "start": 1633368208.7445683,
    "end": 1633973008.7445416,
    "limit": 100,
    "distinct": "site_id",
    "total": 1,
}

Org CoA (Change of Authorization)

Reauth a 802.1x Client

Trigger a CoA against a client

POST /api/v1/orgs/:org_id/clients/:client_mac/coa

Device Profile

While Templates / RF Templates / Network Templates / Gateway Templates provides powerful ways to control how a Device’s configuration is derived for a Site. There are cases where you’d like another level of control at the Org Level.

A Device Profile contains a subset of Device’s configurations you’d like a device to have. It will be merged at runtime when we’re provisioning an AP.

Get All Create Device Profiles

GET /api/v1/orgs/:org_id/deviceprofiles?type=ap
POST /api/v1/orgs/:org_id/deviceprofiles

Get Update Delete Device Profile

GET /api/v1/orgs/:org_id/deviceprofiles/:deviceprofile_id
PUT /api/v1/orgs/:org_id/deviceprofiles/:deviceprofile_id
DELETE /api/v1/orgs/:org_id/deviceprofiles/:deviceprofile_id

Schema

{
    "id": "6f4bf402-45f9-2a56-6c8b-7f83d3bc98e9",
    "type": "ap",  // intended device type, default is AP
    "name": "LowPower",

    // anything provided here will be merged against the devices this profile applies to
    "radio_config": {
        "band_5": {
            "power": 8
        }
    }
}

NOTE: see Device Config

Assign/Unassign Device Profile to/from Devices

POST /api/v1/orgs/:org_id/deviceprofiles/:deviceprofile_id/assign
POST /api/v1/orgs/:org_id/deviceprofiles/:deviceprofile_id/unassign

Request

{
    "macs": [
        "5c5b350e0001",
        "5c5b350e0003"
    ]
}

Response

{
    // devices that has deviceprofile_id changed
    "success": [ "5c5b350e0001" ]
}

Org PSK

Base URI

/api/v1/orgs/:org_id/psks

Add PSK

Add psk on the org. Required: ssid, passphrase.

POST /api/v1/orgs/:org_id/psks

Get PSK

Get list of psks on the org. This API is always paginated, default limit is 100.

Use query param, to filter or sort by name/role/ssid

GET /api/v1/orgs/:org_id/psks?name=Common&role=student&sort=ssid&limit=200&page=3

Delete PSK

Delete list of psks on the org. This API accepts single string or list of strings

POST /api/v1/orgs/:org_id/psks/delete

Example

{
    "psk_ids": ['0039c16c-ca87-4d3f-bb94-b97c58199f18', '6562cc8e-5893-418a-acaa-4d7c1af8084f']
}

Update by PSK name

/api/v1/orgs/:org_id/psks?upsert=true

Example

{
    "name": "Common",
    "passphrase": "foryoureyesonly",
    "ssid": "warehouse",
    "usage": "single",
    "vlan_id": 417,            // optional
    "mac": "5684dae9ac8b",     // optional
    "role": "",                // optional
    "expire_time": 1614990263  // optional, epoch time in seconds, default is null, as no expiration
    "max_usage": 20            // optional, default is 0 (unlimited)
    "notes": "notes"           // optional
    "notify_expiry": true      // optional
    "expiry_notification_time": 2      // optional, unit days
    "notify_on_create_or_edit": true   // optional
    "email": "admin@test.com"  // optional, email to send psk expiring notifications to
    "admin_sso_id": "sso_id"  // optional, sso id for psk created from psk portal
}

Update multi PSKs

PUT /api/v1/orgs/:org_id/psks

Example

[
    {
         "id": "2f64a022-9422-4fa3-92aa-ff6559a9f7f9", //psk_id, required
         "name": "common123",
    },
    {
        "id": "110c59ae-d7b2-40f9-9bf2-82367370e55a", //psk_id, required
        "usage": "single",
        "name": "common12",
        "passphrase": "foryoureyesonly1",
        "role": "teacher",
    }
]

Definitions

Add a psk of type “macs”

Adds a PSK with usage type set to “macs”. When usage==macs, corresponding “macs” field will hold a list consisting of client mac addresses ([“xx:xx:xx:xx:xx”,…]) or mac patterns([“xx:xx:”,”xx”,…]) or both ([“xx:xx:xx:xx:xx:xx”, “xx:*”, …]). This list is capped at 5000

POST /api/v1/orgs/:org_id/psks

Example

{
    "name": "Common",
    "passphrase": "foryoureyesonly",
    "ssid": "warehouse",
    "usage": "macs",
    "macs": ["11:22:33:44:55:66", "aa:bb:*", "53*"],
    "vlan_id": 417,            // optional
    "role": "",                // optional
    "expire_time": 1614990263  // optional, epoch time in seconds, default is null, as no expiration
    "notify_expiry": true      // optional
    "expiry_notification_time": 2      // optional, unit days
    "notify_on_create_or_edit": true   // optional
    "email": "admin@test.com"  // optional, email to send psk expiring notifications to
}

Delete old_passphrase from PSK

POST /api/v1/orgs/:org_id/psks/:psk_id/delete_old_passphrase

If successful, response is same as GET, returns the PSK with old_passphrase removed.

Import PSKs

POST /api/v1/orgs/:org_id/psks/import

Upload via CSV file

A multi-part POST

"file": CSV File

PSK Import CSV File Format

name,ssid,passphrase,usage,vlan_id,mac,max_usage,role,expire_time,notify_expiry,expiry_notification_time,notify_on_create_or_edit,email
Common,warehouse,foryoureyesonly,single,35,a31425f31278,0,student,1618594236
Justin,reception,visible,multi,1002,200,teacher,1618594236
Common2,ssid,1245678-xx,single,35,a31425f31278,0,student,1618594236,true,7,true,admin@test.com

Definitions

Request if Upload via JSON

[
    {
        "name": "Common",
        "ssid": "warehouse",
        "passphrase": "foryoureyesonly",
        "usage": "single",
        "vlan_id", 35,
        "mac": "a31425f31278",
        "max_usage": 300,
        "role": "teacher",
        "expire_time": "1618594236",
        "notify_expiry": true,
        "expiry_notification_time": 2,
        "notify_on_create_or_edit"; true,
        "email": "admin@test.com"
    },
    {
        "name": "Justin",
        "ssid": "reception",
        "passphrase": "visible",
        "usage": "multi",
        "vlan_id", 1002,
        "mac": null,
    },
    {
        "name": "Alice",
        "ssid": "guest",
        "passphrase": "visible",
        "usage": "macs",
        "vlan_id", 1002,
        "macs": ["112233445566", "aabbcc*"]
    }
]

PSK Portal

PSK Self-Service Portals are for

1. WIFI users who want to connect to a WLAN with personal PSK, they’re told to connect to a URL where they can login (likely through company’s SSO) and get the WIFI Name / Passphrase
   • required input fields name, email so we can generate PSK
2. PSK Admins (they don’t have access to normal Network Admin Portal)

Base URL

/api/v1/orgs/:org_id/pskportals

{
    "name": "get-wifi"

    "ssid": "Corp",             // intended SSID

    // for personal psk portal
    "type": "byod",         // byod / admin

    // how PSK should be generated
    "vlan_id": 417,             // optional
    "role": "",                 // optional
    "max_usage": 20,            // optional, default is 0 (unlimited)
    "cleanup_psk": true,        // optional, default is false, used to cleanup exited psk when portal delete or ssid changed

    // auth
    "auth": "sso",              // sso / sponsor(not yet)
    "notification_renew_url": "https://custom-sso/url",    // optional, will include the link in the notification email
    // the customer can either provide their own url or use the one generate from mist, or do a url shorterner against either

    "sso": {
        "issuer": "https://app.onelogin.com/saml/metadata/138130"
        "idp_cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
        "idp_sign_algo": "sha256",
        "idp_sso_url": "https://yourorg.onelogin.com/trust/saml2/http-post/sso/138130",
        "nameid_format": "email",
        // optional
        "allowed_roles": ["Student", "Teather"], // allowed roles for accessing psk portal, if none, any role is permitted.
        "use_sso_role_for_psk_role": true,  // if enabled, the `role` above will be ignored
        "role_mapping": {
            "Student": "user",
            "Teacher": "faculty"
        }
    },

    // rule for generating psk
    "passphrase_rules": {
        "length": 8,
        "max_length": int,              (optional)
        "min_length": int,              (optional)
        "alphabets_enabled": true,
        "numerics_enabled": true,
        "symbols_enabled": false,          // disabled by default
        "symbols": "()[]{}_%@#&$"
        // for valid `max_length` and `min_length`, passphrase size is set randomly from that range.
        // if `max_length` and/or `min_length` are invalid, passphrase size is equal to `length` parameter
        // if `length` is not set or is invalid, default passphrase size is 8.
        // valid `max_length`, `min_length`, `length` should be an integer between 8 to 63. Also, `max_length` > `min_length`
    },
    "expire_time": 1440, // unit min
    "notify_expiry": true,  // optional
    "expiry_notification_time": 2, // optional, unit days
    "notify_on_create_or_edit": true // optional
    "hide_psks_created_by_other_admins": false // optional, for admin psk portal only 

    // what information to ask for (email is required by default)
    "required_fields": ["name", "role"],  // name / notes

    // UI customization
    "bg_image_url": ...
    "thumbnail_url": ...
    "template_url": ...

    // for PSK admin portal
    "type": "admin",
    "auth": "sso",
}

Get SAML Metadata

GET /api/v1/orgs/:org_id/pskportals/:pskportal_id/saml_metadata
GET /api/v1/orgs/:org_id/pskportals/:pskportal_id/saml_metadata.xml

Get Latest SAML Failures

GET /api/v1/orgs/:org_id/pskportals/:pskportal_id/saml_failures

Response

{
    "results": [
        {
            "timestamp": 1431382121,
            "detail": "Role attribute missing",
            "saml_assertion_xml": "<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:nam..."
        }
    ]
}

PskPortal Template

PUT /api/v1/orgs/:org_id/pskportals/:pskportal_id/portal_template

Request

{
  "poweredBy": false,
  "color": "#1074bc",
  "logo": null,
  "alignment": "center",
  "tos": false,
  "tosText": "<< provide your Terms of Service here >>",
  "tosAcceptLabel": "I accept the Terms of Service ",
  "tosLink": "Terms of Service",
  "tosError": "Please review and accept the Terms of Service",
  "tosUrl": "https://company.com/wifi-policy"
}

Parameters

poweredBy|boolean| whether to hide “Powered by Juniper Mist” and email footers, default is false color|string| “#1074bc” logo|string| custom logo with “data:image/png;base64,” format, default null, uses Juniper Mist Logo. alignment|string| defines alignment on portal. “center” is default. tos|boolean| enable terms and service for portal. default is false. tosText|string| terms and service text displayed in footer if tos is enabled. tosAcceptLabel|string| label for accept tos tosLink|string| link for tos tosError|string| error message for not accepting tos tosUrl|string| customized url for defining terms of service

PskPortal Image Upload

Upload background image for PskPortal

POST /api/v1/orgs/:org_id/pskportals/:pskportal_id/portal_image

Request

A multi-part POST

"json": a JSON string describing the upload
"file": a binary file

PskPortal Image Delete

Delete background image for PskPortal

DELETE /api/v1/orgs/:org_id/pskportals/:pskportal_id/portal_image

If image is not uploaded or is deleted, PskPortal will use default image.

GET PskPortal LOGS

GET /api/v1/orgs/:org_id/pskportals/logs?start=1431384000&end=1431298000&limit=100
GET /api/v1/orgs/:org_id/pskportals/logs/search?start=1431384000&end=1431298000&limit=100

Supported Filters

Response

Status: 200 OK
{
    "start": 1428939600,
    "end":   1428954000,
    "limit": 100,

    "total": 135,
    "results": [{
        'timestamp': 1686346104.096, 
        'org_id': '2818e386-8dec-2562-9ede-5b8a0fbbdc71', 
        'psk_name': 'test@mist.com', 
        'psk_id': '608fe603-f9f0-4ce9-9473-04ef6c6ea749', 
        'id': '8a3dcaa7-80e3-4bb0-a75b-7bc6322cfd09', 
        'message': 'Rotate PSK test@mist.com', 
        'pskportal_id': 'c1742c09-af35-4161-96ef-7dc65c6d5674', 
        'name_id': 'test@mist.com'
        }]
}

Count by Distinct Attributes of PskPortal Logs

GET /api/v1/orgs/:org_id/pskportals/logs/count?distinct=user_id

Request

Response

{
    "start": 1511967600,
    "end": 1513177200,
    "limit": 10,
    "distinct": "admin_name",

    "total": 2,
    "results": [
        {
            "admin_name": "John Smith john.smith@corp.com",
            "count": 61
        },
        {
            "admin_name": "Eric Sky eric@corp.com",
            "count": 44
        }
    ]
}

Map Import

Import data from files is a multipart POST which has an file, an optional json, and an optional csv, to create floorplan, assign matching inventory to specific site, place ap if name or mac matches

POST /api/v1/orgs/:org_id/maps/import

Request

A multi-part POST

"json": a JSON string, site id required, vendor option: ekahau, ibwave, etc., import_all_floorplans: optional, default: false,
import_height: optional, default: true, import_orientation: optional, default: true
"file": a binary file, option: .esx
"auto_deviceprofile_assignment": boolean, default: false, whether to auto assign device to deviceprofile by name
"csv": a csv file for ap name mapping, optional
// for the JSON payload
{
    "vendor_name": "ekahau",
    "site_id": "bee1902c-84aa-a993-bee2-d774ed6aa4cf",
    "import_all_floorplans": true,  // optional
    "import_height": true, // optional
    "import_orientation": false // optional
}

Device Import CSV File Format

Vendor AP name,Mist AP Mac
US Office AP-2 - 5c:5b:35:00:00:02,5c5b35000002

Response

{
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "aps": [
        {
            "mac": "5c5b35000001",
            // placed
            "action": "placed"
            "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5"
            // assigned to a site and placed
            "action": "assigned-placed",
            // named and placed
            "action": "named-placed"
            // assigned, named and placed
            "action": "assigned-named-placed"
            // if we ignore it (did nothing with it)
            "action": "ignored",
            "reason": "not found on site" // "not found in inventory",
            // floorplan id, height, orientation for ignored ap
            "floorplan_id": "cbdb7f0b-3be0-4872-88f9-58790b509c23-j68kows8"
            "orientation": 45,
            "height": 3
        }
    ],
    "floorplans": [
        {
            // whatever ID vendor has
            "id": "cbdb7f0b-3be0-4872-88f9-58790b509c23-j68kows8",
            "name": "map1",
            // we only import the floorplan if at least one of the AP is being placed by default
            "action": "imported",
            "map_id": "845a23bf-bed9-e43c-4c86-6fa474be7ae5",
            "action": "ignored",
            "reason": "no aps placed"
        }
    ],
    "summary": {
        "num_ap_assigned": 1,
        "num_map_assigned": 1,
        "num_inv_assigned": 1
    }
}

Org Wired Clients Search

GET /api/v1/orgs/:org_id/wired_clients/search
GET /api/v1/orgs/:org_id/wired_clients/search?mac=112233445566

Request

The following fields are available for searching.

Response

{
    "results": [
        {
            "ip": [
                "11.216.202.61"
            ],
            "device_mac": [
                "001122334455"
            ],
            "org_id": "c168ddee-c14c-11e5-8e81-1258369c38a9",
            "vlan": [
                0,
                1001
            ],
            "site_id": "c168ddee-c14c-11e5-8e81-1258369c38a9",
            "device_mac_port": [
                {
                    "device_mac": "001122334455",
                    "vlan": 1,
                    "ip": "",
                    "start": "2020-12-10T00:07:36.262+0000",
                    "port_id": "et-0/0/1",
                    "port_parent": "",
                    "when": "2022-03-29T04:56:05.172+0000"
                },
            ],
            "mac": "112233445566",
            "timestamp": 1571174567.807,
            "port_id": [
                "et-0/0/1"
            ],
            "dhcp_hostname": "ITS-VMMT0-D1N02",
            "dhcp_fqdn": "ITS-VMMT0-D1N02.mgthub.local",
            "dhcp_client_identifier": "MAC address 00155df6d500",
            "dhcp_vendor_class_identifier": "MSFT 5.0",
            "dhcp_request_params": "1 3 6 15 31 33 43 44 46 47 119 121 249 252",
            "dhcp_client_options": [
                {
                    "code": "DHO_DHCP_MESSAGE_TYPE(53)", 
                    "data": "DHCPREQUEST"
                }, {
                    "code": "DHO_DHCP_CLIENT_IDENTIFIER(61)",
                    "data": "MAC address 00155df6d500",  
                }, {
                    "code": "DHO_DHCP_REQUESTED_ADDRESS(50)",
                    "data": "172.17.10.255",
                }, {
                    "code": "DHO_DHCP_SERVER_IDENTIFIER(54)",
                    "data": "172.17.8.1"
                }, {
                    "code": "DHO_DHCP_MAX_MESSAGE_SIZE(57)",
                    "data": "1280"
                }, {
                    "code": "DHO_DHCP_PARAMETER_REQUEST_LIST(55)",
                    "data": " 1 3 6 12 15 28 43 180"
                }, {
                    "code": "DHO_VENDOR_CLASS_IDENTIFIER(60)",
                    "data": "MSFT 5.0"
                }, {
                    "code": "DHO_HOST_NAME(12)",
                    "data": "ITS-VMMT0-D1N02"
                }
            ],
            "auth_method": "mac_auth",
            "auth_state": "authenticated"
        }
    ],
    "start": 1648443400.8221116,
    "end": 1648529800.8221116,
    "limit": 1000,
    "total": 1
}

Count Org Wired Clients by Distinct Attributes

GET /api/v1/orgs/:org_id/wired_clients/count

Request

Response

{
    "start": 1648443400.8221116,
    "end": 1648529800.8221116,
    "limit": 1000,
    "distinct": "device_mac",
    "total": 20,
    "results": [
        {
            "device_mac": "112233445566",
            "count": 7
        },
        {
            "device_mac": "aabbccddeeff",
            "count": 2
        },
        ...
    ]
}

Org Wired Clients Events Search

GET /api/v1/orgs/:org_id/wired_clients/events/search
GET /api/v1/orgs/:org_id/wired_clients/events/search?mac=112233445566

Request

The following fields are available for searching.

Response

{
    "results": [
        {
            "device_mac": "device_mac",
            "timestamp": 1594708454.257958,
            "org_id": "1688605f-916a-47a1-8c68-f19618300a08",
            "site_id": "ec3b5624-73f1-4ed3-b3fd-5ba3ee40368a",
            "port_id": "ge-0/0/5",
            "type": "SW_DOT1XD_USR_AUTHENTICATED",
            "text": "text",
            "mac": "mac"
        }

    ],
    "start": 1663038067.062201,
    "end": 1663113667.0622225,
    "limit": 1000,
    "total": 1
}

Count Org Wired Clients by Distinct Attributes

GET /api/v1/orgs/:org_id/wired_clients/events/count

Request

Response

{
    "results": [{
        "count": 1,
        "type": "SW_DOT1XD_USR_AUTHENTICATED"
    }],
    "start": 1663038067.062201,
    "end": 1663113667.0622225,
    "limit": 1000,
    "distinct": "type",
    "total": 1,
    "percentage": 100
}

Doing CoA against a wired client

POST /api/v1/orgs/:org_id/wired_clients/:mac/coa

Request

Response

{
    "device_mac": "5c5b35000002",
    "port_id": "ge-0/0/0",
    "session": "0a2a11b8-4b30-40d8-a6d1-e91ea540d86f"
}

Tickets

Get Tickets of an Org

GET /api/v1/orgs/:org_id/tickets?start=1546300800&end=-1d

Parameters

NOTE: if both start & duration are specified, duration will be ignored

Response

[
    {
        "id": "00000000-0000-0000-0000-00000000000c",
        "case_number": "12",
        "created_at": 1453908369,
        "updated_at": 1453908369,
        "subject": "Please add me",
        "type": "question",
        "status": "open",
        "requester": "John Smith",
        "requester_email": "joe@abc.com"
    }
]

Definitions

Ticket Status

• open: ticket is open, Mist is working on it
• pending: ticket is open and Requester attention is needed (e.g. Mist is asking for some more information)
• solved: ticket is marked as solved / considered by Mist (requester can update it, causing it to re-open; or rate it)
• closed: ticket is archived and cannot be changed

Create a ticket

POST /api/v1/orgs/:org_id/tickets

Example

{
    "subject": "question regarding WPA",
    "type": "question",
    "comment": "where do I configure WPA1 / WPA2 / Auto?"
}

Definitions

Update a ticket

PUT /api/v1/orgs/:org_id/tickets/:ticket_id

Example

{
    "subject": "question regarding WPA/WPA2",
    "type": "question",
    "status": "solved"
}

Definitions

Add a comment

POST /api/v1/orgs/:org_id/tickets/:ticket_id/comments

Example (no attachments)

{
    "comment": "this is urgent"
}

Example (with attachments)

multipart:
"comment": "this is urgent, see my screenshot",
"file": a binary file

Get Ticket Detail

GET /api/v1/orgs/:org_id/tickets/:ticket_id

Response

{
    "id": "00000000-0000-0000-0000-00000000000c",
    "case_number": "12",
    "created_at": 1453908369,
    "updated_at": 1453908369,
    "subject": "Please add me",
    "type": "bug",
    "status": "open",
    "requester": "John Smith",
    "requester_email": "joe@abc.com",
    "comments: [
        {
            "comment": "this is urgent, see my screenshot",
            "created_at": 1453908369,
            "author": "John Smith",
            "attachment_ids": ["00000000-0000-0000-0000-15231a659c13"]
        }
    ],
    "attachments": [
        {
            "id": "00000000-0000-0000-0000-15231a659c13",
            "file_name": "crash.png",
            "created_at": 1453908369,
            "content_url": "https://api.mist.com/api/v1/forward/download?jwt=..."
            "content_type": "image/png",
            "size_in_bytes": 1943
        },
        {
            "id": "00000000-0000-0000-0000-15231a659c78",
            "file_name": "crash.log",
            "created_at": 1453908369,
            "content_url": "https://api.mist.com/api/v1/forward/download?jwt=..."
            "content_type": "text/plain",
            "size_in_bytes": 2532
        }
    ]
}

Add an attachment

POST /api/v1/orgs/:org_id/tickets/:ticket_id/attachments

Example

multipart:
"file": a binary file

Get Ticket Attachment Download URL

GET /api/v1/orgs/:org_id/tickets/:ticket_id/attachments/:attachment_id

Response

{
    "content_url": "https://api.mist.com/api/v1/forward/download?jwt=..."
}

Count tickets

GET /api/v1/orgs/:org_id/tickets/count?distinct=status

Definitions

Response

{
    "limit": 1000,
    "distinct": "status",
    "total": 5,
    "results": [
        {
            "status": "closed",
            "count": 24
        },
        {
            "status": "open",
            "count": 12
        },
        {
            "status": "solved",
            "count": 15
        },
        {
            "status": "pending",
            "count": 10
        },
        {
            "status": "hold",
            "count": 3
        }
    ]
}

SSO / SAML

Create SSO

POST /api/v1/orgs/:org_id/ssos

Request

{
    "name": "onelogin",

    "idp_type": "saml",  // saml (default) / ldap / oauth / mxedge_proxy / openroaming

    "issuer": "https://app.onelogin.com/saml/metadata/138130"
    "idp_cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
    "idp_sign_algo": "sha256",
    "idp_sso_url": "https://yourorg.onelogin.com/trust/saml2/http-post/sso/138130",
    "nameid_format": "email",

    // some IdP support a custom logout URL that is different from SP-initiated SLO process
    "custom_logout_url": "https://6.4.5.7/saml/idp/SingleLogoutService.php?param1=value1"

    // if idp_type = ldap
    "ldap_type": "azure", // azure (default) / okta / google / custom
    // if ldap_type is NOT custom:
    //     filters are automatically chosen based on chosen ldap_type
    // if ldap_type = custom:
    //     user can specify below fileds:
    //     ldap_user_filter
    //     ldap_group_attr (optional, default is memberOf)
    //     ldap_group_dn (optional, default is base_dn)
    //     ldap_group_filter (optional, default is user_filter)
    "ldap_server_hosts": [ "hostname", "63.1.3.5" ],
    "ldap_base_dn": "DC=abc,DC=com",
    "ldap_bind_dn": "CN=nas,CN=users,DC=abc,DC=com",
    "ldap_bind_password": "credential_for_nas",
    "ldap_cacerts": [
        "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
        "-----BEGIN CERTIFICATE-----\nBhMCRVMxFDASBgNVBAoMC1N0YXJ0Q29tIENBMSwwKgYDVn-----END CERTIFICATE-----"
    ],
    "ldap_client_cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
    "ldap_client_key": "-----BEGIN PRI...",
    "ldap_resolve_groups": false,  // whether to recursively resolve LDAP groups, default is false

    // if idp_type = oauth
    "oauth_type": "azure", // azure (default) / azure-gov / okta / ping_identity
    // if oauth_type is okta/ping_identity, oauth_tenant_id is of the form "dev-88336535"
    "oauth_tenant_id": "1e6ae660-b7d3-4a6c-9efd-1fa606fc7304",
    // cc = Client Credentialstunbne
    "oauth_cc_client_id": "e60da615-7def-4c5a-8196-43675f45e174",
    // if oauth_type is okta/ping_identity, oauth_cc_client_secret is RSA private key, of the form "-----BEGIN RSA PRIVATE KEY--...."
    "oauth_cc_client_secret": "akL8Q~5kWFMVFYl4TFZ3fi~7cMdyDONi6cj01cpH",
    "oauth_ping_identity_region": "us", // us (United States, default), ca (Canada), eu (Europe), asia (Asia), au (Australia) 
    // ropc = Resource Owner Password Credentials
    "oauth_ropc_client_id": "9ce04c97-b5b1-4ec8-af17-f5ed42d2daf7",
    // oauth_ropc_client_secret can be empty if oauth_type is azure or azure-gov
    "oauth_ropc_client_secret": "blM9R~6kWFMVFYl4TFZ3fi~8cMdyDONi6cj01dqI",
    // scim_enabled (default 'false') indicates if SCIM provisioning is enabled for the OAuth IDP
    "scim_enabled": false,
    // scim_secret_token (auto-generated when not provided by caller and scim_enabled=true, empty string when scim_enabled=false) is used as the Bearer token in the Authorization header of SCIM provisioning requests by the IDP
    "scim_secret_token": "FBitbKPE1aecSloPGBuqqPxDUrFeZyZk",

    // if idp_type = mxedge_proxy
    // this requires `mist_nac` to be enabled on the mxcluster
    "mxedge_proxy": {
        "mxcluster_id": "572586b7-f97b-a22b-526c-8b97a3f609c4",
        "proxy_hosts": ["mxedge1.corp.com", "63.1.3.5"], // public hostname/IPs
        "ssids": ["eduroam_test, eduroam_main"],  // SSIDs that support eduroam, default: "eduroam"
        "operator_name": "1dartmouth.edu", // Operator name as Radius attribute while proxying
        "auth_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123",
                "require_message_authenticator": true, // default is false
            },
            {
                "host": "radius.internal",
                "port": 1812,
                "secret": "testing123",
                "timeout": 3, // seconds. default is 5
                "retries": 1, // default is 2
             }
        ],
        "acct_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123",
            }
        ]
    },

    // if idp_type = openroaming
    "openroaming": {
        // SSIDs that support OpenRoaming
        "ssids": ["ssid_name1", "ssid_name2"],

        // Optional WBA-issued certificate. If not provided, the default WBA-issued certificate for Juniper will be used.
        "wba_cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----"
    },

    // common
    "ignore_unmatched_roles": false,
    "default_role": null,
}

Definition

Supported Role Parsing Schemes

Get All SSO Configured for the Org

GET /api/v1/orgs/:org_id/ssos

Response

[
    {
        "name": "onelogin",
        "issuer": "https://app.onelogin.com/saml/metadata/138130"
        "idp_cert": "-----BEGIN CERTIFICATE-----\nMIIFZjCCA06gAwIBAgIIP61/1qm/uDowDQYJKoZIhvcNAQELBQE\n-----END CERTIFICATE-----",
        "idp_sign_algo": "sha256",
        "idp_sso_url": "https://yourorg.onelogin.com/trust/saml2/http-post/sso/138130"
    }
]

Update SSO

PUT /api/v1/orgs/:org_id/ssos/:sso_id

Delete SSO

DELETE /api/v1/orgs/:org_id/ssos/:sso_id

Get SSO Metadata

GET /api/v1/orgs/:org_id/ssos/:sso_id/metadata

Response

{
   // if idp_type = saml (default)
   "entity_id": "https://api.mist.com/api/v1/saml/llDfa13f/login",
   "acs_url": "https://api.mist.com/api/v1/saml/llDfa13f/login",
   "logout_url": "https://api.mist.com/api/v1/saml/llDfa13f/logout",
   "metadata_xml": "<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://api.mist.com/api/v1/saml/llDfa13f/login" validUntil="2027-10-12T21:59:01Z" xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat><md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.mist.com/api/v1/saml/llDfa13f/login" index="0" isDefault="true"/></md:SPSSODescriptor></md:EntityDescriptor>"

   // if idp_type = oauth and scim_enabled
    "scim_base_url": "https://scim.nac-staging.mistsys.com/S_41b2525a-e8b8-4809-8168-f1d8dcbe9735/azure/4d72b1dc-7503-4717-81ea-80d0125b886e"

}

Download SAML Metadata

GET /api/v1/orgs/:org_id/ssos/:sso_id/metadata.xml

Response

<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://api.mist.com/api/v1/saml/5hdF5g/login" validUntil="2027-10-12T21:59:01Z" xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.mist.com/api/v1/saml/5hdF5g/logout" />
        <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.mist.com/api/v1/saml/5hdF5g/login" index="0" isDefault="true"/>
        <md:AttributeConsumingService index="0">
            <md:ServiceName xml:lang="en-US">Mist</md:ServiceName>
            <md:RequestedAttribute Name="Role" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="true"/>
            <md:RequestedAttribute Name="FirstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
            <md:RequestedAttribute Name="LastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false"/>
        </md:AttributeConsumingService>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

Get Latest SSO Failures

GET /api/v1/orgs/:org_id/ssos/:sso_id/failures

Response

{
    "results": [
        {
            "timestamp": 1431382121,
            "detail": "Role attribute missing",
            "saml_assertion_xml": "<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:nam..."
        }
    ]
}

Create SSO Role

POST /api/v1/orgs/:org_id/ssoroles

Request

{
    "name": "NOC",
    "privileges": [
        { "scope":"org", "role": "admin", "view": "reporting" },
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "admin", "view": "reporting" },
        { "scope":"sitegroup", "sitegroup_id": "581328b6-e382-f54e-c9dc-999983183a34", "role": "admin", "view": "reporting" }
    ]
}

Definition

Update SSO Role

PUT /api/v1/orgs/:org_id/ssoroles/:ssorole_id

Request

{
    "name": "NOC",
    "privileges": [
        { "scope":"site", "site_id": "d96e3952-53e8-4266-959a-45acd55f5114", "role": "write", "view": "location" },
        { "scope":"site", "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b", "role": "write", "view": "location" }
    ]
}

Get All SSO Roles

GET /api/v1/orgs/:org_id/ssoroles

Delete SSO Role

DELETE /api/v1/orgs/:org_id/ssoroles/:ssorole_id

Subscriptions

Subscriptions define how Org Alarms/Reports are delivered to whom

Subscribe

POST /api/v1/orgs/:org_id/subscriptions

Unsubscribe

DELETE /api/v1/orgs/:org_id/subscriptions

Get all the subscriptions

GET /api/v1/self/subscriptions

Search

Search Devices

GET /api/v1/orgs/:org_id/devices/search?ip=10.2.16.205

Supported Filters for device type AP

Response for device type AP

{
    "results": [
        {
            "mac": "5c5b353e5299",
            "model": "AP41",
            "sku": "AP41-US",
            "ip": "10.2.16.205",
            "version": "0.7.20216",
            "uptime": 85280,
            "org_id": "6748cfa6-4e12-11e6-9188-0242ac110007",
            "site_id": "a8178443-ecb5-461c-b854-f16627619ab3",
            "mxedge_id": "00000000-0000-0000-1000-43a81f238391",
            "mxedge_ids": [
                "00000000-0000-0000-1000-43a81f238391"
            ],
            "mxtunnel_status": "down",
            "hostname": [
                            "AP41-STB-3E5299-WH-2001",
                            "AP41-STB-3E5299-WH-50",
                            "AP41-STB-3E5299",
                            "5c5b353e5299"
                        ],
            "lldp_port_desc": "GigabitEthernet1/0/1",
            "lldp_mgmt_addr": "10.2.10.139",
            "lldp_system_desc": "Cisco IOS Software, C2960S Software (C2960S-UNIVERSALK9-M), Version 15.2(1)E1, RELEASE SOFTWARE (fc2)\nTechnical Support: http://www.cisco.com/techsupport\nCopyright (c) 1986-2013 by Cisco Systems, Inc.\nCompiled Fri 22-Nov-13 07:10 by prod_rel_team",
            "lldp_system_name": "ME-DC-1-ACC-SW",
            "lldp_port_id": "Gi1/0/1",
            "lldp_power_draw": 19500,
            "lldp_power_allocated": 19500,
            "band_24_power": 18,
            "band_24_channel": 6,
            "band_6_power": 10,
            "band_6_channel": 5,
            "band_5_power": 17,
            "band_5_channel": 44,
            "eth0_port_speed": 1000,
            "ext_ip": "125.228.68.139",
            "timestamp": 1596588619.007,
            "power_constrained": false
        }
    ]
}

Supported Filters for device type Switch or Gateway

radius_stats

Response for device type Switch or Gateway

{
    "results": [
        {
            "ip": "192.168.86.22",
            "type": "switch",
            "version": "21.4R1.12",
            "mac": "3c8c939485ad",
            "uptime": 2380356,
            "ext_ip": "0.0.0.0",
            "hostname": [
                "3c8c939485ad",
                "ludi-ex2300"
            ],
            "timestamp": 1661273225.321,
            "org_id": "6748cfa6-4e12-11e6-9188-0242ac110007",
            "num_members": 1,
            "site_id": "8721e817-96ee-4e34-b6b6-a80cc01642a6",
            "model": "ex2300-c-12p",
            "last_hostname": "3c8c939485ad"
            "last_config_status": "success",
            "radius_stats": {
              "192.168.1.10": {
                "auth_accepts": 120,
                "auth_rejects": 5,
                "auth_timeouts": 0,
                "auth_server_status": "up"
              },
              "192.168.1.11": {
                "auth_accepts": 110,
                "auth_rejects": 15,
                "auth_timeouts": 2,
                "auth_server_status": "unreachable"
              }
            }
        }
    ]
}

Count Devices

GET /api/v1/orgs/:org_id/devices/count?distinct=model

Response

{
    "end": 1545874660.211871,
    "distinct": "model",
    "results": [
        {
            "count": 22,
            "model": "AP41-US"
        }
    ],
    "start": 1545788260.21184,
    "limit": 10,
    "total": 1
}

Search Devices Events

GET /api/v1/orgs/:org_id/devices/events/search?ip=10.2.10.22

Supported Filters

Supported Events Type

GET /api/v1/const/device_events

Response

{
    "results": [
        {
            "org_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862a",
            "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
            "ap": "5c5b351e13b5",
            "apfw": "5c5b351e13b5",
            "model": "BT11-WW",
            "text": """Succeeding DNS query from 172.29.101.134 to 172.29.101.7 for "portal.mistsys.com" on vlan 1, id 60224""",
            "timestamp": 1547235620.89,
            "type": "CLIENT_DNS_OK"
        },
        ...
    ]
}

Fetch most recent device events.

Return last/recent event for passed in field

GET /api/v1/orgs/:org_id/devices/events/search?last_by=type

Response

{
    "results": [
        {
            "timestamp": 1685566764.144,
            "org_id": "98272e44-d31d-4e9a-b52d-18ae2183446e",
            "site_id": "b60a57e3-dd74-4da3-af12-02987a141665",
            "port_id": "xe-2/2/2",
            "type": "SW_PORT_UP",
            "model": "EX4300-48MP",
            "device_type": "switch",
            "text": "SNMP_TRAP_LINK_UP: ifIndex 894, ifAdminStatus up(1), ifOperStatus up(1), ifName xe-2/2/2",
            "version": "21.4R3-S3.4",
            "mac": "c042d0f52a00"
        },
        {
            "timestamp": 1685566645.128,
            "org_id": "98272e44-d31d-4e9a-b52d-18ae2183446e",
            "site_id": "b60a57e3-dd74-4da3-af12-02987a141665",
            "type": "SW_VC_MEMBER_ADDED",
            "model": "EX4300-48MP",
            "device_type": "switch",
            "text": "CHASSISD_VCHASSIS_MEMBER_OP_NOTICE: Member change: vc add of member 2",
            "version": "21.4R3-S3.4",
            "mac": "c042d0f52a00"
        }
    ],
    "total": 234266
}

Fetch most recent device events including prisma events

Return last/recent event for passed in field

GET /api/v1/orgs/:org_id/devices/events/search?includes=ext_tunnel&last_by=type

Response

{
    "results": [
        {
            "timestamp": 1531855800.128,
            "org_id": "98272e44-d31d-4e9a-b52d-18ae2183446e",
            "site_id": "b60a57e3-dd74-4da3-af12-02987a141665",
            "type": "SW_VC_MEMBER_ADDED",
            "model": "EX4300-48MP",
            "device_type": "switch",
            "text": "CHASSISD_VCHASSIS_MEMBER_OP_NOTICE: Member change: vc add of member 2",
            "version": "21.4R3-S3.4",
            "mac": "c042d0f52a00"
        },
        {
           "tunnel_name": "Prisma-Tunnel-II",
           "type": "PRISMA_RN_SECONDARY_WAN_TUNNEL_UP",
           "text": "Remote Network Site RN_SITE_1 SECONDARY WAN Tunnel Stage-Tunnel2 is down",
           "timestamp": 1531856649,
           "ext_tunnel_site": "RN_SITE_1",
           "ext_tunnel_name": "Stage-Tunnel2",
           "ext_tunnel_event_id": b1b1ccdd-4444-4a2d-a81d-8888bc8f6fa1",
           "ext_tunnel_debug_url": "https://stratacloudmanager.paloaltonetworks.com/incidents-alerts/logviewer?logType=log.system&query=Event%25C2%25A0Component%20=%20%27RN_SITE_1%27%20OR%20Event%25C2%25A0Component%20=%20%27Stage-Tunnel2%27%20&timePreset=custom&startTime=1745977906000&endTime=1745980306000&queryMode=lq",
           "site_id: "f1e17c67-8e42-4a2d-a81d-98ddbc8f6fa1",
           "org_id: "f3045b5a-f2ea-445e-b923-5bbb5a670c35",
           "device_type: "gateway",
           "mac: "00c52c3cfaa4",
           "port_id: "reth2.0",
           "ext_tunnel_provider": "prisma"
        },
    {
       "tunnel_name": "Prisma-Tunnel-II",
       "type": "PRISMA_RN_SECONDARY_WAN_TUNNEL_DOWN",
       "text": "Remote Network Site RN_SITE_1 SECONDARY WAN Tunnel Stage-Tunnel2 is down",
       "timestamp": 1531855849,
           "ext_tunnel_site": "RN_SITE_1",
           "ext_tunnel_name": "Stage-Tunnel2",
           "ext_tunnel_event_id": b1b1ccdd-4444-4a2d-a81d-8888bc8f6fa1",
           "ext_tunnel_debug_url": "https://stratacloudmanager.paloaltonetworks.com/incidents-alerts/logviewer?logType=log.system&query=Event%25C2%25A0Component%20=%20%27RN_SITE_1%27%20OR%20Event%25C2%25A0Component%20=%20%27Stage-Tunnel2%27%20&timePreset=custom&startTime=1745977906000&endTime=1745980306000&queryMode=lq",
           "site_id: "f1e17c67-8e42-4a2d-a81d-98ddbc8f6fa1",
           "org_id: "f3045b5a-f2ea-445e-b923-5bbb5a670c35",
           "device_type: "gateway",
           "mac: "00c52c3cfaa4",
           "port_id: "reth2.0",
           "ext_tunnel_provider": "prisma"
    }
    ],
    "total": 234266
}

Count Devices Events

GET /api/v1/orgs/:org_id/devices/events/count?distinct=model

Response

{
    "end": 1545874660.211871,
    "distinct": "model",
    "results": [
        {
            "count": 22,
            "model": "AP41-US"
        }
    ],
    "start": 1545788260.21184,
    "limit": 10,
    "total": 1
}

Count Devices Events including prisma events

GET /api/v1/orgs/:org_id/devices/events/count?includes=ext_tunnel&distinct=type

Response

{
    "distinct": "type",
    "results": [
        {
            "count": 1,
            "type": "PRISMA_RN_PRIMARY_WAN_TUNNEL_UP"
        },
        {
            "count": 1,
            "type": "PRISMA_RN_PRIMARY_WAN_TUNNEL_DOWN"
        },
        {
            "count": 2,
            "type": "PRISMA_RN_SECONDARY_WAN_BGP_DOWN"
        },
        {
            "count": 1,
            "type": "PRISMA_RN_SECONDARY_WAN_BGP_UP"
        }
    ],
    "start": 1531776183.0,
    "end": 1531862583.0,
    "limit": 10,
    "total": 4
}

Search Device Last Configs

GET /api/v1/orgs/:org_id/devices/last_config/search?device_type=ap&mac=5c5b350e0001&start=1531776183&end=1531862583&limit=10

Request Parameters

Response

see (Search Device Config History)[Site#search-device-config-history]

Count Device Last Configs

Counts the number of entries in device config history for distinct field with given filters

GET /api/v1/orgs/:org_id/devices/last_config/count?device-type=ap&distinct=mac&start=1531776183&end=1531862583&limit=10

Search Wireless Clients

GET /api/v1/orgs/:org_id/clients/search?hostname=john&limit=10

Supported Filters

Response

{
    "results": [
        {
            "hostname": [
                "jerry"
            ],
            "ap": [
                "5c5b350e0492",
                "5c5b350eb39d",
                "5c5b350e03c0"
            ],
            "ip": [
                "192.168.5.43",
                "192.168.20.125"
            ],
            "vlan": [
                1
            ],
            "mac": "60f81dd250cc",
            "device": [
                "Mac"
            ],
            "os": [
                "Sierra",
                "High Sierra"
            ],
            "model": [
                "",
                "MBP 15\" late 2013"
            ],
            "ssid": [
                "Guest"
            ],
            "psk_id": [
                "9d31efe6-e205-47eb-9f1d-dd66d8ef66bd"
            ],
            "psk_name": [
                "test key"
            ],
        }
        ...
    ]
}

Count by Distinct Client-Search Attributes

GET /api/v1/orgs/:org_id/clients/count?distinct=hostname

Request

NOTE: the filters from /clients/search can also be used. E.g. /clients/count?device=iphone&distinct=os

Search Client Events

GET /api/v1/orgs/:org_id/clients/events/search

Request

Response

{
    "start": 1512572151,
    "end": 1513176951,
    "limit": 10,

    "total": 1,
    "results": [
        {
            "ap": "5c5b350eb31b",
            "ssid": "Guest",
            "bssid": "5c5b350918f1",
            "proto": "ac",
            "timestamp": 1513358874.667,
            "band": "5",
            "type_code": 15,
            "type": "CLIENT_DNS_OK",
            "text": "Status code 0 \"Successful\" ",
            "channel": 149,
            "key_mgmt": "WPA2-EAP-FT/CCMP",
            "wlan_id": "be22bba7-8e22-e1cf-5185-b880816fe2cf"
        }
    ]
}

Count by Distinct Attributes of Client-Events

GET /api/v1/orgs/:org_id/clients/events/count?distinct=type

Request

NOTE: the filters from /clients/:mac/events can also be used. E.g. /clients/events/count?distinct=device&ssid=Guest

Response

{
    "start": 1513276353,
    "end": 1513362753,
    "limit": 3,

    "total": 3,
    "results": [
        {
            "count": 580,
            "type": "CLIENT_AUTHENTICATED"
        },
        {
            "count": 536,
            "type": "CLIENT_GW_ARP_OK"
        },
        {
            "count": 519,
            "type": "CLIENT_ASSOCIATION"
        }
    ]
}

Search Client Sessions

GET /api/v1/orgs/:org_id/clients/sessions/search

Request

Response

{
    "start": 1511967600,
    "end": 1513177200,
    "limit": 10,
    "total": 100,
    "results": [
        {
            "ap": "5c5b350e0262",
            "disconnect": 1565208448.662,
            "ssid": "Dummy WLAN 2",
            "tags": [
                "disassociate"
            ],
            "org_id": "3139f2c2-fac6-11e5-8156-0242ac110006",
            "site_id": "70e0f468-fc13-11e5-85ad-0242ac110008",
            "mac": "b019c66c8348",
            "connect": 1565208388.568,
            "band": "5",
            "timestamp": 1565208448.662,
            "duration": 60.09423865,
            "client_manufacture": "Apple",
            "wlan_id": "99bb4c74-f954-4f36-b844-6b030faffabc",
            "psk_id": "8a4a134b-210a-4908-a6be-105dca78e226",
            "psk_name": "test key"
        },
        ...
    ]
}

Count by Distinct Attributes of Client Sessions

GET /api/v1/orgs/:org_id/clients/sessions/count

Request

In addition to the filters that you can have in the search

NOTE: the filters from /clients/sessions/search can also be used. (E.g. /clients/count?distinct=client_manufacture)

Response

{
    "start": 1511967600,
    "end": 1513177200,
    "limit": 100,
    "distinct": "client_manufacture",
    "total": 20,
    "results": [
        {
            "count": 217,
            "client_manufacture": "Apple"
        },
        {
            "count": 35,
            "client_manufacture": "Intel Corporate"
        },
        ...
    ]
}

Get Org Guest Authorizations

GET /api/v1/orgs/:org_id/guests

Response

[
    {
        "mac": "5684dae9ac8b",
        "authorized": true,
        "authorized_time": 1480704355,
        "authorized_expiring_time": 1480704955,
        "name": "John Smith",
        "email": "john@abc.com",
        "company": "abc",
        "field1": "xxx",
        "wlan_id": "6748cfa6-4e12-11e6-9188-0242ac110007",
        "ssid": "SSID"
    }
]

Get Guest Authorization

GET /api/v1/orgs/:org_id/guests/:guest_mac

Response

[
    {
        "mac": "5684dae9ac8b",
        "authorized": true,
        "authorized_time": 1480704355,
        "authorized_expiring_time": 1480704955,
        "name": "John Smith",
        "email": "john@abc.com",
        "company": "abc",
        "field1": "xxx",
        "wlan_id": "6748cfa6-4e12-11e6-9188-0242ac110007",
        "ssid": "SSID"

    }
]

Update Guest Authorization

PUT /api/v1/orgs/:org_id/guests/:guest_mac

Request

{
    "name": "guest1",
    "email": "guest1@email.com",
    "company":"companyXYZ",
    "minutes": 60,
    "field1": "value1",
    "wlan_id": "6748cfa6-4e12-11e6-9188-0242ac110007"
    ......
}

Delete Guest Authorization

DELETE /api/v1/orgs/:org_id/guests/:guest_mac

Search Authorized Guest

GET /api/v1/orgs/:org_id/guests/search?wlan_id=88ffe630-95b8-11e8-b294-346895ed1b7d&limit=2

Response

{
    "end": 1531862583.0,
    "results": [
        {
            "ssid": "openNet",
            "timestamp": 1531782218,
            "company": "mistsystems",
            "auth_method": "passphrase",
            "ap": "5c5b350e0001",
            "authorized_expiring_time": 1531810258.186273,
            "authorized_time": 1531782218,
            "email": "user@mistsys.com",
            "name": "john"
        },
        {
            "ssid": "openNet",
            "timestamp": 1531782632,
            "company": "xyz inc.",
            "auth_method": "facebook",
            "ap": "5c5b350e0001",
            "authorized_expiring_time": 1531810821.145,
            "authorized_time": 1531782632,
            "email": "cool_user@yahoo.com",
            "name": "John White"
        }
    ],
    "next": "/api/v1/orgs/8aaba0aa-09cc-44bd-9709-33b98040550c/guests/search?wlan_id=88ffe630-95b8-11e8-b294-346895ed1b7d&end=1531855849.000&limit=2&start=1531776183.0",
    "start": 1531776183.0,
    "limit": 2,
    "total": 14
}

Count Authorized Guest

GET /api/v1/orgs/:org_id/guests/count?distinct=auth_method

Response

{
    "end": 1531862583.0,
    "results": [
        {
            "auth_method": "passphrase",
            "count": 2
        },
        {
            "auth_method": "facebook",
            "count": 4
        }
    ],
    "start": 1531776183.0,
    "total": 2
}

Count by Distinct Attributes of Skyatp Events (WIP)

GET /api/v1/orgs/:org_id/skyatp/events/count?distinct=type

Request

Response

{
    "start": 1511967600,
    "end": 1513177200,
    "limit": 10,
    "distinct": "type",

    "total": 2,
    "results": [
        {
            "type": "mw",
            "count": 6
        },
        {
            "device": "fs",
            "count": 3
        }
    ]
}

Search Skyatp Events (WIP)

GET /api/v1/orgs/:org_id/skyatp/events/search

Request

Response

{
    "start": 1512572151,
    "end": 1513176951,
    "limit": 10,

    "total": 1,
    "results": [
        {
            "mac": "b019c66c8348",
            "threat_level": 7,
            "device_mac": "658279bb1fa4",
            "timestamp": 1592524478,
            "org_id": "3139f2c2-fac6-11e5-8156-0242ac110006",
            "site_id": "70e0f468-fc13-11e5-85ad-0242ac110008",
            "type": "cc",
            "ip": "172.16.0.11"
        }
    ]
}

Search Sites

GET /api/v1/orgs/:org_id/sites/search?honeypot_enabled=true

Supported Filters

Response

{
    "results": [
        {
            "rogue_enabled": true,
            "honeypot_enabled": true,
            "mesh_enabled": true,
            "locate_unconnected": true,
            "wifi_enabled": true,
            "timezone": "America/Los_Angeles",
            "country_code": "US",
            "created_time": 1670284377.225059,
            "modified_time": 1687888493.799605,
            "org_id": "3139f2c2-fac6-11e5-8156-0242ac110006",
            "name": "Mist Site",
            "id": "70e0f468-fc13-11e5-85ad-0242ac110008",
            "auto_upgrade_version": "stable",
            "auto_upgrade_enabled": true,
            "analytic_enabled": true
        }
    ],
    "limit": 10,
    "total": 1
}

Count Sites

GET /api/v1/orgs/:org_id/sites/count?distinct=country_code

Request

Response

{
    "results": [
        {
            "country_code": "US",
            "count": 15
        },
        {
            "country_code": "IN",
            "count": 2
        },
        {
            "country_code": "SE",
            "count": 1
        }
    ],
    "distinct": "country_code",
    "limit": 10,
    "total": 3
}

Search Switch / Gateway Ports

GET /api/v1/orgs/:org_id/stats/ports/search

see Site:Search Switch / Gateway Ports for API request & response details.

Count by Distinct Attributes of Switch Ports

GET /api/v1/orgs/:org_id/stats/ports/count

see Site:Count by Distinct Attributes of Switch Ports for API request & response details.

Security Policy

Overview

Security Policy is designed to audit / catch discripancies between “what’s intended to be running” versus “what’s actually running” in a network. Many big organizations have separated Security and IT team (for good reasons). Each site can be assigned a security policy. Whenever an AP is provisioned, the configuration will be checked against the security policy. Any violations will be flagged in Device Config History where you can search for the when and where the violation occurs.

Base URI

/api/v1/orgs/:org_id/secpolicies

Schema

{
    "name": "corporate only",
    "wlans": [
        {
            "ssid": "office",
            "band": "both",
            "auth": {
                "type": "psk",
                "pairwise": ["wpa1-tkip", "wpa2-tkip"]
            }
        },
        {
            "ssid": "office-guest",
            "band": "5",
            "auth": {
                "type": "open"
            }
        }
    ]
}

Alarm

Overview

Alarms are triggered based on certain events. Alarms could be configured using an Alarm Template.

An Alarm Template is a set of Alarm Rules that could be applied to one or more sites (while each site can only pick one Alarm Template), or to the whole org.

Alarm Templates

Base URI

/api/v1/orgs/:org_id/alarmtemplates

Create Alarm Template

POST /api/v1/orgs/:org_id/alarmtemplates

Body

{
    "name": "Global",
    "delivery": {
        "enabled": false,
        "to_org_admins": true,
        "to_site_admins": true,
        "additional_emails": []
    },
    "rules": {
        "switch_down": { // here switch_down is an <alarm-key>
            "enabled": true,
        },
        "device_down": {
            "enabled": true,

            // optional, if different from that in the template
            "delivery": {
                "enabled": false,
                "to_org_admins": true,
                "to_site_admins": true,
                "additional_emails": []
            }
        }
    }
}

Parameters

delivery

rules

Response

Status: 200 OK

Body

{
    "id": "684dfc5c-fe77-2290-eb1d-ef3d677fe168",
    "name": "Global",
    "delivery": {
        "enabled": false,
        "to_org_admins": true,
        "to_site_admins": true,
        "additional_emails": []
    },
    "rules": {
        "switch_down": {
            "enabled": true,
        },
        "device_down": {
            "enabled": true,

            // optional, if different from that in the template
            "delivery": {
                "enabled": false,
                "to_org_admins": true,
                "to_site_admins": true,
                "additional_emails": []
            }
        }
    }
}

Definitions

Note: Rest of the fields are same as defined in the API request Org:Alarm Template:Create Alarm Template:Response:Body.

List all Alarm Templates

GET /api/v1/orgs/:org_id/alarmtemplates

Parameters

Response

Status: 200 OK

Body

List of Alarm Templates

Get an Alarm Template

GET /api/v1/orgs/:org_id/alarmtemplates/:alarmtemplate_id

Parameters

Response

Status: 200 OK

Body

See Org:Alarm Template:Create Alarm Template:Response:Body

Update an Alarm Template

PUT /api/v1/orgs/:org_id/alarmtemplates/:alarmtemplate_id

Body

See Org:Alarm Template:Create Alarm Template:Body

Parameters

Response

Status: 200 OK

Body

See Org:Alarm Template:Create Alarm Template:Response:Body

Delete an Alarm Template

DELETE /api/v1/orgs/:org_id/alarmtemplates/:alarmtemplate_id

Parameters

Response

Status: 200 OK

Get Alarm Definitions

Get brief definitions of all the supported alarm types. The example field contains an example payload as you would recieve in the alarm webhook output.

GET /api/v1/const/alarm_defs

Response

[
    {
        "key": "device_down",
        "display": "Device offline",
        "group": "infrastructure",
        "severity": "warn",
        "example": {
            "severity": "warn",
            "timestamp": 1629753888,
            "last_seen": 1629753888,
            "aps": [
                "d420b02000fa"
            ],
            "org_id": "09dac91f-6e73-4100-89f7-698e0fafbb1b",
            "site_id": "dcfb31a1-d615-4361-8c95-b9dde05aa704",
            "count": 1,
            "hostnames": [
                "Vendor_AP2"
            ],
            "id": "f70c308f-7007-4866-9ecd-0d01842979ea",
            "type": "device_down",
            "group": "infrastructure"
        },
        "fields": [
            "aps",
            "hostnames"
        ]
    },
    ...
]

Suppress Alarms for a period of time

In certain situations, for example, scheduled maintenance, you may want to suspend alarms to be triggered against Sites for a period of time.

POST /api/v1/orgs/:org_id/alarmtemplates/suppress

Request

{
    "duration": 3600,  // 0 is to un-suppress alarms
    "scheduled_time": 1678232980,
    "scope": "site",  // default is site
    "applies": {
        "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
        "sitegroup_ids": [ "581328b6-e382-f54e-c9dc-999983183a34", "f57096b9-0c2f-4df6-c77b-ae6ae87a3d43" ],
        "site_ids": [ "4ac1dcf4-9d8b-7211-65c4-057819f0862b" ]
    }
}

// to suppress org alarms
{
    "duration": 3600,  // 0 is to un-suppress alarms
    "scheduled_time": 1678232980,
    "scope": "org"
}

GET Current Suppressed Alarms

GET /api/v1/orgs/:org_id/alarmtemplates/suppress?scope=site

Request

Response

{
    "results": [
        {
            "site_id": "581328b6-e382-f54e-c9dc-9c998d183a34",
            "expire_time": 1678233080,
            "scheduled_time": 1678232900,
            "duration": 48,    // remaining duration
            "scope": "site",
        },
        {
            "site_id": "581328b6-e382-f54e-c9dc-9c998d183a35",
            "expire_time": 1678233080,
            "scheduled_time": 1678232900,
            "duration": 48,    // remaining duration
            "scope": "org",
        }
    ]
}

Un-Suppress Suppressed Alarms

DELETE /api/v1/orgs/:org_id/alarmtemplates/suppress

Ack An alarm

Acknowledge an alarm within an org.

POST /api/v1/orgs/:org_id/alarms/:alarm_id/ack

see Site:Ack An alarm for API request & response details.

Unack An alarm

Unacknowledge an alarm within an org.

POST /api/v1/orgs/:org_id/alarms/:alarm_id/unack

see Site:Unack An alarm for API request & response details.

Ack multiple alarms

Acknowledge multiple alarms at once within an org.

POST /api/v1/orgs/:org_id/alarms/ack

see Site:Ack mutiple alarms for API request & response details.

UnAck multiple alarms

Unacknowledge multiple alarms at once within an org.

POST /api/v1/orgs/:org_id/alarms/unack

see Site:UnAck mutiple alarms for API request & response details.

Ack all alarms

Acknowledge all the alarms of an org.

POST /api/v1/orgs/:org_id/alarms/ack_all

see Site:Ack all alarms for API request & response details.

Unack all alarms

Unacknowledge all the alarms of an org.

POST /api/v1/orgs/:org_id/alarms/unack_all

see Site:Unack all alarms for API request & response details.

Get Alarms

List or Search alarms within an org.

GET /api/v1/orgs/:org_id/alarms/search

see Site:Get Alarms for API request & response details.

Count Alarms

Count alarms within an org.

GET /api/v1/orgs/:org_id/alarms/count

see Site:Count Alarms for API request & response details.

Mist Edge

Overview

Mist Edge is a software component outside of Mist Cloud. Stay tuned for what it can do.

Get All Mist Edges

GET /api/v1/orgs/:org_id/mxedges

Parameters

Response

[
    {
        "id": "95ddd29a-6a3c-929e-a431-51a5b09f36a6",
        "name": "Guest",
        "model": "ME-100",
        "magic": "L-NpT5gi-ADR8WTFd4EiQPY3cP5WdSoD",
        "tunterm_registered": true,
        "mxagent_registered": true,

        "mxedge_mgmt": {
            "mist_password": "MIST_PASSWORD",
            "root_password": "ROOT_PASSWORD",
            "config_auto_revert": true, // default is false
        },

        "oob_ip_config": {
            "type": "static",    // dhcp (default) / static / disabled
            "ip": "10.2.1.10",
            "netmask": "255.255.255.0",
            "gateway": "10.2.1.254",

            "type6": "static",   // autoconf (default) / dhcp / static / disabled
            "ip6": "2601:1700:43c0:dc0:20c:29ff:fea7:93bc",
            "netmask6": "/64",
            "gateway6": "2601:1700:43c0:dc0::1",

            // IPv4 ignored if type!=static
            // IPv6 ignored if type6!=static
            "dns": ["10.2.1.2", "2601:1700:43c0:dc0::2"],  // default is ["8.8.8.8", "4.4.4.4" , "2001:4860:4860::8888", "2001:4860:4860::8844"]
        },

        "proxy": {
            "url": "http://proxy.internal:8080/"
        },

        "tunterm_ip_config": {
            "ip": "10.2.1.1", // VLAN ID 1
            "netmask": "255.255.255.0",
            "gateway": "10.2.1.254",
            "ip6": "2001:1010:1010:1010::2", // VLAN ID 1
            "netmask6": "/64",
            "gateway6": "2001:1010:1010:1010::1",
        },

        "tunterm_other_ip_configs": {
            "5": { // VLAN ID
                "ip": "10.3.3.1",
                "netmask": "255.255.255.0",
            }
        },

        "tunterm_extra_routes": {
            "11.0.0.0/8": {
                "via": "10.3.3.1"
            }
        },

        "tunterm_dhcpd_config": {
            "enabled": false,
            "servers": ["11.2.3.4"],
            "2": {
                "enabled": true,
                "servers": ["11.2.3.44"],
            }
        },

        "tunterm_port_config": {
            // draft, not finalized
            "separate_upstream_downstream": true,
            "downstream_ports": ["3"],
            "upstream_ports": [ "0", "1", "2" ],
            "upstream_port_vlan_id": 30
        },

        // if custom vlan settings are desired
        "tunterm_switch_config": {
            "enabled": true,
            "0": {  // port0
                "vlan_ids": [1, 3055],
                "port_vlan_id": 1
            }
        },

        // overwrite mxcluster or site settings when set
        "tunterm_monitoring": [
            {
                "protocol": "ping",   // arp / ping / tcp
                "host": "10.2.8.15",  // can be ip, ipv6, hostname
                "timeout": 300,  // 60 - 3600, default is 300

                // when protocol==tcp
                "port": 80,

                // optional source for the monitoring check, vlan_id configured in tunterm_other_ip_configs
                "src_vlan_id": 5
            }
        ],

        "ntp_servers": [],

        "mxcluster_id": "572586b7-f97b-a22b-526c-8b97a3f609c4",

        "tunterm_igmp_snooping_config": {
             "enabled": true,
             "vlan_ids": [2, 3, 5],
             "querier": {
                  "query_interval": 125,
                  "max_response_time": 10,
                  "robustness": 2,
                  "version": 3,
                  "mtu": 1500
             }
        },

        "tunterm_multicast_config": {
            "mdns": {
                "enabled": true,
                "vlan_ids": [2, 3, 5]
            },
            "ssdp": {
                "enabled": true,
                "vlan_ids": [2, 3, 5]
            }
        }
    }
]

Mxedge OOB IP Config

Mxedge Mist Tunnel IP Config

Mxedge Mist Tunnel VLAN IP Config

Extra Routes for Mist Tunneled VLANs

DHCP server/relay for Mist Tunneled VLANs

Tunterm IGMP Snooping Config

Create Mist Edge

POST /api/v1/orgs/:org_id/mxedges

Request

{
    "name": "Guest",
    "model": "ME-100",
    "services": ["tunterm"],
    "versions": {
        "mxagent": "2.4.194",
        "tunterm": "0.1.928-1"
    },
    "ntp_servers": [],
    "mxedge_mgmt": {},
    "oob_ip_config": {},
    "notes": "note for mxedge"
    "proxy": {},
    "tunterm_ip_config": {
        "ip": "10.2.1.1", // VLAN ID == "1"
        "netmask": "255.255.255.0",
        "gateway": "10.2.1.254", // default route
    },
    "tunterm_port_config": {
        "separate_upstream_downstream": true, // default == false
        "downstream_ports": [ "0", "1", "2", "3" ], // default == available ports
        "upstream_ports": [ "0", "1", "2", "3" ], // default == available ports
        "upstream_port_vlan_id": 1,
    },
    "tunterm_switch_config": {
        "enabled": true, // default == false
        "0": {"vlan_ids": [5, 2, 3], "port_vlan_id": None}
    },
    "mxcluster_id": "572586b7-f97b-a22b-526c-8b97a3f609c4"
}

Response

{
    "id": "95ddd29a-6a3c-929e-a431-51a5b09f36a6",
    "name": "Edge1",
    "magic": "ExNpT5gi-ADR8WTFd4EiQPY3cP5WdSoD",
    "tunterm_registered": false,
    "mxagent_registered": false,
    "mxcluster_id": "572586b7-f97b-a22b-526c-8b97a3f609c4"
}

Assign Mist Edge To a Site

POST /api/v1/orgs/:org_id/mxedges/assign

Request

{
    "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
    "mxedge_ids": ["387804a7-3474-85ce-15a2-f9a9684c9c90"]
}

Response

{
    "success": ["387804a7-3474-85ce-15a2-f9a9684c9c90"]
}

Unassign Mist Edge from Sites

POST /api/v1/orgs/:org_id/mxedges/unassign

Request

{
    "mxedge_ids": ["387804a7-3474-85ce-15a2-f9a9684c9c90"]
}

Response

{
    "success": ["387804a7-3474-85ce-15a2-f9a9684c9c90"]
}

Update Mist Edge

PUT /api/v1/orgs/:org_id/mxedges/:mxedge_id

Request

{
    "name": "Guest",
    "model": "ME-100",
    "services": ["tunterm"],
    "versions": {
        "mxagent": "2.4.194",
        "tunterm": "0.1.928-1"
    },
    "ntp_servers": [],
    "notes": "note for mxedge"

    "tunterm_ip_config": {
        "ip": "10.2.1.1",
        "netmask": "255.255.255.0",
        "gateway": "10.2.1.254"
    },
    "tunterm_port_config": {
        "upstrem": {
            "ports": [ "0", "1", "2", "3" ]
        },
        "downstream": {
            "ports": [ "0", "1", "2", "3" ],
            "port_vlan_id": 1 
        }
    },

    "mxcluster_id": "572586b7-f97b-a22b-526c-8b97a3f609c4"
}

Unregister a Mist Edge

In the case where a Mist Edge is replaced, you would need to unregister it. Which disconnects the currently the connected Mist Edge and allow another to register.

POST /api/v1/orgs/:org_id/mxedges/:mxedge_id/unregister

Delete Mist Edge

DELETE /api/v1/orgs/:org_id/mxedges/:mxedge_id

Search Mist Edges

GET /api/v1/orgs/:org_id/mxedges/search

Supported Filters

Response

{
    "results": [
        {
            "last_seen": 1695151551.833,
            "org_id": "35d96b1a-1a13-4ba8-90f5-1e78dd2a10c5",
            "mxedge_id": "00000000-0000-0000-1000-d420b0f0025d",
            "tunterm_version": "0.1.2813",
            "model": "ME-X5",
            "distro": "buster",
            "uptime": 5662632
        },
        {
            "last_seen": 1695151550.622,
            "org_id": "23ab5425-55d8-4d4e-98a8-f572a11e9282",
            "mxedge_id": "00000000-0000-0000-1000-d420b0f0042b",
            "model": "ME-X1",
            "distro": "buster",
            "uptime": 2842400
        }
    ],
    "start": 1694622179,
    "end": 1694708579,
    "limit": 10,
    "total": 2
}

Count Mist Edges

GET /api/v1/orgs/:org_id/mxedges/count?distinct=model

Request

Response

{
    "results": [
        {
            "model": "ME-100",
            "count": 27
        },
        {
            "model": "ME-X1",
            "count": 8
        },
    ],
    "start": 1694622935,
    "end": 1694709335,
    "limit": 10,
    "distinct": "model",
    "total": 2
}

Restart a Mist Edge

POST /api/v1/orgs/:org_id/mxedges/:mxedge_id/restart

Control Services on a Mist Edge

POST /api/v1/orgs/:org_id/mxedges/:mxedge_id/services/:name/:action

Parameters

Upload Mist Edge support files

Support / Upload Mist Edge support files

POST /api/v1/orgs/:org_id/mxedges/:mxedge_id/support

Bounce TunTerm Data Ports

POST /api/v1/orgs/:org_id/mxedges/:id/services/tunterm/bounce_port

Request

{
    "ports": ["0", "2"]
}

Parameters

Disconnect AP’s from TunTerm

POST /api/v1/orgs/:org_id/mxedges/:id/services/tunterm/disconnect_aps

Request

{
   "macs": ["5c5b353e4eb1", "5c5b353e4eb2"]
}

Parameters

Upgrade Mist Edges

POST /api/v1/orgs/:org_id/mxedges/upgrade

Request

{
    // filters that can be used, if no filter specified, it means entire org
    "mxedge_ids": ["387804a7-3474-85ce-15a2-f9a9684c9c90"],

    "channel": "stable",

    // version initially installed: highest qualified version at that time
    "versions": {
        "mxagent": "latest",       // highest version
        "tunterm": "default"       // highest qualified version (<=latest)
        "radsecproxy": "<version>" // specific <version> e.g. 1.9.1-1.mist.12
    },
    "allow_downgrades": {
        "mxagent": false,
        "tunterm": true
    },
    "strategy": "serial",
    "canary_phases": [5,25,50,100],
    "max_failures": [1,1,5,5], // will be used if provided, else max_failure_percentage will be used
    "max_failure_percentage": 5,
    "start_time": 1624399840,
}

Upgrade Mist Edges’s Distro

POST /api/v1/orgs/:org_id/mxedges/upgrade

Request

{
    // filters that can be used, if no filter specified, it means entire org
    "mxedge_ids": ["387804a7-3474-85ce-15a2-f9a9684c9c90"],

    "distro": "buster",  // buster

    "strategy": "serial",
    "canary_phases": [5,25,50,100],
    "max_failures": [1,1,5,5], // will be used if provided, else max_failure_percentage will be used
    "max_failure_percentage": 5,
    "start_time": 1624399840,
}

Get Mist Edge Upgrades

GET /api/v1/orgs/:org_id/mxedges/upgrade

Response

[{
    "status": "upgrading",
    "strategy": "serial",
    "versions": {},
    "channel": "stable",
    "id": "ceef2c8a-e2e6-447a-8b27-cb4f3ec1adae",
    "counts": {
        "queued": 1,
        "upgrading": 1,
        "success": 0,
        "failed": 0
    }
}]

Get Mist Edge Upgrade

GET /api/v1/orgs/:org_id/mxedges/upgrade/:upgrade_id

Response

{
    "status": "upgrading",
    "strategy": "serial",
    "versions": {},
    "channel": "stable",
    "id": "5cbcee0a-c620-4bb4-a25e-15000934e9d8",
    "targets": {
        "queued": ["387804a7-3474-85ce-15a2-f9a9684c9c90"],
        "upgrading": ["8e525f1d-4178-4ae1-a988-2b0176855e55"],
        "success": [],
        "failed": []
    }
}

Get Mist Edge Upgrade Information

GET /api/v1/orgs/:org_id/mxedges/versions?channel=stable&distro=<codename>

Response

[
    {
        "package": "mxagent",
        "version": "2.4.100",
        "_version": "2.4.100",
        "distro": "bullseye",
        "default": true
    },
    {
        "package": "tunterm",
        "version": "1.0.0",
        "distro": "buster",
        "_version": "1.0.0-nd"
    }
]

Get Mist Edge Models

GET /api/v1/const/mxedge_models

Response

[
    {
        "model": "ME-100",
        "display": "ME-Small",
        "ports": {
            "0": {
                "display": "Gigabit Ethernet 0",
                "speed": 1000
            },
            "1": {
                "display": "Gigabit Ethernet 1",
                "speed": 1000
            },
            "2": {
                "display": "Gigabit Ethernet 2",
                "speed": 1000
            },
            "3": {
                "display": "Gigabit Ethernet 3",
                "speed": 1000
            }
        }
    }
]

Attach MxEdge Image

Attach up to 3 images to a mxedge

POST /api/v1/orgs/:org_id/mxedges/:id/image1
POST /api/v1/orgs/:org_id/mxedges/:id/image2
POST /api/v1/orgs/:org_id/mxedges/:id/image3

Remove MxEdge Image

Delete up to 3 images which are attached to a mxedge

DELETE /api/v1/orgs/:org_id/mxedges/:id/image1
DELETE /api/v1/orgs/:org_id/mxedges/:id/image2
DELETE /api/v1/orgs/:org_id/mxedges/:id/image3

Get Supported Mist Edge Events

GET /api/v1/const/mxedge_events

Response

[
    {
        "key": "ME_CONFIG_CHANGED_BY_USER",
        "display": "ME Config changed by user",
        "description": "Config change on ME was triggered as a result of change made by user",
        "example": {
            "type": "ME_CONFIG_CHANGED_BY_USER",
            "service": "mxagent",
            "timestamp": 1552408871,
            "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
            "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
            "mxcluster_id": "ed4665ed-c9ad-4835-8ca5-dda642765ad3",
            "mxedge_id": "387804a7-3474-85ce-15a2-f9a9684c9c90",
            "audit_id": "e9a88814-fa81-5bdc-34b0-84e8735420e5"
        }
    },
    {
        "key": "ME_CONFIGURED",
        "display": "ME Configured",
        "description": "ME received and applied a new config",
        "example": {
            "type": "ME_CONFIGURED",
            "timestamp": 1552408871,
            "org_id": "2818e386-8dec-2562-9ede-5b8a0fbbdc71",
            "site_id": "4ac1dcf4-9d8b-7211-65c4-057819f0862b",
            "mxcluster_id": "ed4665ed-c9ad-4835-8ca5-dda642765ad3",
            "mxedge_id": "387804a7-3474-85ce-15a2-f9a9684c9c90",
            "audit_id": "e9a88814-fa81-5bdc-34b0-84e8735420e5"
        }
    },
    ...
]

Search Mist Edge Events

GET /api/v1/orgs/:org_id/mxedges/events/search

Supported Filters

Response

{
    "results": [
        {
            "mxcluster_id": "2815c917-58e7-472f-a190-bfd44fb58d05",
            "timestamp": 1694678225.927,
            "org_id": "f2695c32-0e83-4936-b1b2-96fc88051213",
            "mxedge_id": "00000000-0000-0000-1000-020000dc585c",
            "type": "ME_SERVICE_STOPPED",
            "service": "tunterm"
        },
        {
            "timestamp": 1694678004.821,
            "org_id": "f2695c32-0e83-4936-b1b2-96fc88051213",
            "mxedge_id": "00000000-0000-0000-1000-020000dc585c",
            "type": "ME_SERVICE_STARTED",
            "service": "tunterm"
        },
         {
            "package": "radsecproxy",
            "timestamp": 1694678010.108,
            "org_id": "f2695c32-0e83-4936-b1b2-96fc88051213",
            "mxedge_id": "00000000-0000-0000-1000-020000dc585c",
            "type": "ME_PACKAGE_INSTALLED",
            "to_version": "1.9.1-1.mist.16"
        },
        {
            "timestamp": 1694679111.253,
            "org_id": "f2695c32-0e83-4936-b1b2-96fc88051213",
            "mxedge_id": "00000000-0000-0000-1000-020000dc585c",
            "type": "ME_POWERINPUT_DISCONNECTED",
            "component": "PS1"
        }
    ],
    "start": 1694622179,
    "end": 1694708579,
    "limit": 10,
    "total": 4
}

Count Mist Edge Events

GET /api/v1/orgs/:org_id/mxedges/events/count?distinct=type

Request

Response

{
    "results": [
        {
            "type": "ME_SERVICE_RESTARTED",
            "count": 5003
        },
        {
            "type": "ME_SERVICE_STARTED",
            "count": 124
        },
        {
            "type": "ME_SERVICE_FAILED",
            "count": 120
        }
    ],
    "start": 1694622935,
    "end": 1694709335,
    "limit": 10,
    "distinct": "type",
    "total": 3
}

Mist Edge Cluster

Overview

A Mist Edge Cluster represents a group of Mist Edges that will work together to do load-balancing and handle fail-overs.

Base URI

/api/v1/orgs/:org_id/mxclusters

Schema

{
    "id": "572586b7-f97b-a22b-526c-8b97a3f609c4",
    "name": "Guest Cluster",

    "proxy": {
        "url": "http://proxy.corp.com:8080/"
    },

    "mxedge_mgmt": {
        "fips_enabled": true, // default is false
        "oob_ip_type": "disabled",  // dhcp (default) / disabled
        "oob_ip_type6": "disabled", // autoconf (default) / dhcp / disabled
        "config_auto_revert": true, // default is false
    },

    // for AP, how to connect to tunterm or radsecproxy
    "tunterm_hosts": ["guest-sj1.corp.com"],
    "tunterm_ap_subnets": [
        "0.0.0.0/0"
    ],
    "tunterm_hosts_selection": "shuffle",
    // if tunterm_hosts_selection is ordered, then re-order with tunterm_hosts with tunterm_hosts_order
    "tunterm_hosts_order": [0, 1],

    "mist_das": {
        // configure cloud-assisted dynamic authorization service on this cluster of mist edges
        "enabled": true,
        "coa_servers": [  // dynamic authorization clients configured to send CoA|DM to mist edges on port 3799
            {
                "enabled": false,
                "host": "aaa.internal",
                "secret": "testing456",
                "require_message_authenticator": false,
                "disable_event_timestamp_check": false
            }
        ],
    },

    "radsec": {
        // configure radsecproxy service on this cluster of mist edges
        "enabled": true,
        "proxy_hosts": ["mxedge1.corp.com"], // must be superset of all wlans[*].radsec.proxy_hosts
        "match_ssid": false,
        "server_selection": "ordered",
        "auth_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123",
                "ssids": ["corporate"],

                // if used for Mist AP
                "keywrap_enabled": true, // enable keywrap algorithm. Default is false
                "keywrap_format": "hex", // key format: hex or ascii
                “keywrap_kek”: “1122334455", // Key encryption key
                “keywrap_mack” “1122334455", // Message Authentication Code Key
            },
            {
                "host": "radius.internal",
                "port": 1812,
                "secret": "testing123",
                "require_message_authenticator": true,
                "ssids": ["guest"],
                "inband_status_check": true,
                "inband_status_interval": 60,
                "timeout": 3, // seconds. default is 5
                "retries": 1, // default is 2
            }
        ],
        "acct_servers": [
            {
                "host": "1.2.3.4",
                "port": 1812,
                "secret": "testing123",
            }
        ],
        "src_ip_source": "tunnel",
        "nas_ip_source": "tunnel",
    },


    // mist_nac
    "mist_nac": {
        "enabled": true,
        "secret": "testing123",

        "client_ips": {
            "10.0.3.0/24": {

                // convention to be followed is : "<vendor>-<variant>"
                // <variant> could be an os/platform/model/company
                // for ex: for cisco vendor, there could variants wrt
                // os (such as ios, nxos etc), platforms (asa etc),
                // or acquired companies (such as meraki, airnonet) etc.
                //
                // currentluy supported vendor values are:
                // generic, juniper, aruba, paloalto, brocade
                // cisco-aironet, cisco-ios, cisco-meraki, cisco-dnac

                "vendor": "cisco-ios",
                "secret": "alternative_one",  // optional, if different from above
                "require_message_authenticator": true, // default is false
                "site_id": "00000000-0000-0000-1234-000000000000"  // optional; present only for 3rd party clients
            }
        },

        "auth_server_port": 1812,  // optional, default is 1812
        "acct_server_port": 1813,  // optional, default is 1813
    }

    "tunterm_monitoring_disabled": false,
    "tunterm_monitoring": [
         {
             "protocol": "ping",   // arp / ping / tcp
             "host": "10.2.8.15",  // can be ip, ipv6, hostname
             "timeout": 300,  // 60 - 3600, default is 300

             // when protocol==tcp
             "port": 80
         }
    ],

    "tunterm_extra_routes": {
        "11.0.0.0/8": {
            "via": "10.3.3.1"
        }
    },

    // default type == "relay"
    "tunterm_dhcpd_config": {
        "enabled": false, // required
        "servers": ["11.2.3.4"],
        "2": { // VLAN ID
            "enabled": true, // required
            "servers": ["11.2.3.44"],
        }
    },

    "tunterm_multicast_config": {
        "mdns": {
            "enabled": true,
            "vlan_ids": [2, 3, 5]
        },
        "ssdp": {
            "enabled": true,
            "vlan_ids": [2, 3, 5]
        },
        "multicast_all": true
    }
}

Dynamic Authorization (mist_das)

enabled|boolean| whether to enable mist das, default is false coa_servers|list| list of COA (change of authorization) servers allowed as dynamic authorization clients; default for enabled is false require_message_authenticator|boolean| whether to require Message-Authenticator in requests, default is false disable_event_timestamp_check|boolean| whether to disable Event-Timestamp Check, optional, default is false

RADIUS Proxy (radsec)

RADIUS Server