Introduction

The KPN SD-LAN SD-WAN Network View & Network Manager APIs offer an interface for software to interact directly with the KPN SD-LAN SD-WAN products, based on the Cisco Meraki cloud platform and Cisco Meraki managed devices. The API contains a set of endpoints for use cases such as provisioning, configuration changes and monitoring.

The API resources follow a structure like in the image below. Organizations consist of networks, which contain devices such as access points, switches and MX security appliances. The characteristics of these devices can be configured with the API.

Meraki Dashboard overview

The KPN SD-LAN SD-WAN API is a REST API using HTTPS requests to a URL and JSON as a human-readable format.

The API call volume rate is limited to 5 calls per second per organization.


API specification

Test the API on SwaggerHub


Base URL

https://api-prd.kpn.com/kpn/meraki


Conceptual model

Conceptual model

Description

  1. You communicate a change of your ICT environment to My API Store through the SD-LAN SD-WAN API.
  2. My API Store immediately moves the change to the Cisco Meraki cloud platform.
  3. The cloud platform returns a notification if the change is accepted.
  4. After that, the Meraki controller performs the change in your ICT environment.


2 API levels

Depending on your user credentials you can access different levels of the API:

  • the SD-LAN SD-WAN Network View API.
  • the SD-LAN SD-WAN Network Manager API.

Network View API

Users with read rights can retrieve information from the Network View API resources.

Allowed methods: GET

Network Manager API

Users with read and write rights can access the Network Manager API resources, where you can:

  • Retrieve information from resources.
  • Add new API resources.
  • Change properties in existing API resources.

Allowed methods: GET/PUT/POST

User credentials

You need to create a separate project for both the Network View API and the Network Manager API in the My API Store. Both projects will have separate user credentials.


Requirements

This API is only available for customers of KPN SD-LAN SD-WAN services based on Cisco Meraki.


Definitions

Layer 3 (L3) firewall rule

L3 firewall rules provide administrators granular access control of client traffic. Layer 3 firewalls filter traffic, based on the TCP/IP stack. This approach is sometimes also referred to as packet filtering because you’re essentially allowing and blocking individual network packets depending on where they originated and which ports they want to talk to.

MAC address

In a local area network (LAN) or other network, the MAC (Media Access Control) address is the computer's unique hardware number.

MX

Cisco Meraki MX Security Appliances are multi-functional security & SD-WAN enterprise appliances, with a wide set of capabilities to address multiple use cases from an all-in-one device.

PoE

Power over Ethernet (PoE) is a technology for wired Ethernet local area networks (LANs) that allows the electrical current necessary for the operation of each device to be carried by the data cables rather than by power cords.

Quality of Service (QoS)

QoS is the description or measurement of the overall performance of a service, such as a telephony, computer network or a cloud computing service, particularly the performance seen by the users of the network.

SSID

Service Set Identifier. A “service set” refers to a collection of wireless networking devices with the same parameters. SSIDs serve as "wireless network names" and are typically natural language labels.

Switch

A network switch is a device that connects different network segments together transparently.

Switch port

A network switch port is a physical interface on the switch where devices connect to the switch.

VLAN

A VLAN (virtual LAN) is a sub-network, which can group together collections of devices on separate physical local area networks (LANs).


API workflow

Meraki Dashboard Workflow


Features

  • Retrieve information about your organization, networks, devices, VLANs, and more.
  • Create new VLANs, QoS rules, port schedules.
  • Configure aspects of your networks & devices in minutes.


Getting started

Make sure you've read Getting Started for more info on how to register your application and start trying out our APIs.

Authentication

The API follows the KPN Store API Authentication Standard to secure the API. It includes the use of OAuth 2.0 client_id and client_secret to receive an access token.

Go to the Authentication tab on top of this page to find out how to:

  • Authenticate to an API using cURL.
  • Authenticate to an API on Swaggerhub.
  • Import Open API Specifications (OAS), also called Swagger files into Postman.


How to... (Network View endpoints)


Parameters marked with an asterisk are required. Example: serial*.

Retrieve Layer 3 firewall rules for MX appliances

This endpoint returns the L3 firewall rules for an MX appliance.

Request

GET /networks/{networkId}/l3FirewallRules

Path parameter Type Description
networkId* string Network identity is a portion of the TCP/IP address that is used to identify individuals or devices on a network such as a local area network or the Internet.

Response

^^Response example^^
Successful HTTP Status: 200
[
  {
    "comment": "Allow TCP traffic to subnet with HTTP servers.",
    "policy": "allow",
    "protocol": "tcp",
    "destPort": 443,
    "destCidr": "192.168.1.0/24",
    "srcPort": "Any",
    "srcCidr": "Any",
    "syslogEnabled": false
  }
]

Retrieve a list of switch ports

Lists the switch ports for a switch.

Request

GET /devices/{serial}/switchPorts

Path parameter Type Description
serial* string The serial number of the device. Example: Q7QN-9J8L-SGTD
Query parameter Type Description
t0 string The beginning of the timespan for the data. The maximum lookback period is 31 days from today.
timespan integer The timespan for which the information will be fetched. If specifying timespan, do not specify parameter t0. The value must be in seconds and be less than or equal to 31 days. The default is 1 day.

Response

^^Response example^^
Successful HTTP Status: 200
[
    {
        "number": 1,
        "name": "My switch port",
        "tags": "tag1 tag2",
        "enabled": true,
        "poeEnabled": true,
        "type": "access",
        "vlan": 10,
        "voiceVlan": 20,
        "isolationEnabled": false,
        "rstpEnabled": true,
        "stpGuard": "disabled",
        "accessPolicyNumber": "1234",
        "linkNegotiation": "Auto negotiate",
        "portScheduleId": "1234",
        "udld": "Alert only",
        "macWhitelist": [
            "34:56:fe:ce:8e:a0",
            "34:56:fe:ce:8e:a1"
        ],
        "stickyMacWhitelist": [
            "34:56:fe:ce:8e:b0",
            "34:56:fe:ce:8e:b1"
        ],
        "stickyMacWhitelistLimit": 5,
        "stormControlEnabled": true
    }
]

Retrieve a specific switch port

Request

GET /devices/{serial}/switchPorts/{number}

Path parameter Type Description
serial* string The serial number of the device. Example: Q7QN-9J8L-SGTD
number* string The number of the device. Example: Q7QN-9J8L-SGTD

Response

^^Response example^^
Successful HTTP Status: 200
{
    "number": 1,
    "name": "My switch port",
    "tags": "tag1 tag2",
    "enabled": true,
    "poeEnabled": true,
    "type": "access",
    "vlan": 10,
    "voiceVlan": 20,
    "isolationEnabled": false,
    "rstpEnabled": true,
    "stpGuard": "disabled",
    "accessPolicyNumber": "1234",
    "linkNegotiation": "Auto negotiate",
    "portScheduleId": "1234",
    "udld": "Alert only",
    "macWhitelist": [
        "34:56:fe:ce:8e:a0",
        "34:56:fe:ce:8e:a1"
    ],
    "stickyMacWhitelist": [
        "34:56:fe:ce:8e:b0",
        "34:56:fe:ce:8e:b1"
    ],
    "stickyMacWhitelistLimit": 5,
    "stormControlEnabled": true
}

Retrieve a list of Service Set Identifiers (SSID)

Lists the SSIDs in a network. Supports networks with access points or wireless-enabled security appliances and teleworker gateways.

Request

GET /networks/{networkId}/ssids

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791

Response

^^Response example^^
Successful HTTP Status: 200
[
    {
        "number": 0,
        "name": "My SSID",
        "enabled": true,
        "splashPage": "Click-through splash page",
        "ssidAdminAccessible": false,
        "authMode": "8021x-radius",
        "encryptionMode": "wpa-eap",
        "wpaEncryptionMode": "WPA2 only",
        "radiusServers": [
            {
                "host": "0.0.0.0",
                "port": 3000
            }
        ],
        "radiusAccountingEnabled": false,
        "radiusEnabled": true,
        "radiusAttributeForGroupPolicies": "Filter-Id",
        "radiusFailoverPolicy": "null",
        "radiusLoadBalancingPolicy": "null",
        "ipAssignmentMode": "NAT mode",
        "adminSplashUrl": "http://example.com",
        "splashTimeout": "30 minutes",
        "walledGardenEnabled": true,
        "walledGardenRanges": "example.com",
        "minBitrate": 11,
        "bandSelection": "5 GHz band only",
        "perClientBandwidthLimitUp": 0,
        "perClientBandwidthLimitDown": 0,
        "visible": true,
        "availableOnAllAps": false,
        "availabilityTags": [ "test-tag" ]
    }
]

Retrieve a single SSID

Returns a specific Service Set Identifier (SSID).

Request

GET /networks/{networkId}/ssids/{number}

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791
number* string The number of the SSID instance.

Response

^^Response example^^
Successful HTTP Status: 200
{
    "number": 0,
    "name": "My SSID",
    "enabled": true,
    "splashPage": "Click-through splash page",
    "ssidAdminAccessible": false,
    "authMode": "8021x-radius",
    "encryptionMode": "wpa-eap",
    "wpaEncryptionMode": "WPA2 only",
    "radiusServers": [
        {
            "host": "0.0.0.0",
            "port": 3000
        }
    ],
    "radiusAccountingEnabled": false,
    "radiusEnabled": true,
    "radiusAttributeForGroupPolicies": "Filter-Id",
    "radiusFailoverPolicy": "null",
    "radiusLoadBalancingPolicy": "null",
    "ipAssignmentMode": "NAT mode",
    "adminSplashUrl": "http://example.com",
    "splashTimeout": "30 minutes",
    "walledGardenEnabled": true,
    "walledGardenRanges": "example.com",
    "minBitrate": 11,
    "bandSelection": "5 GHz band only",
    "perClientBandwidthLimitUp": 0,
    "perClientBandwidthLimitDown": 0,
    "visible": true,
    "availableOnAllAps": false,
    "availabilityTags": [ "test-tag" ]
}


How to... (Network Manager endpoints)

Parameters marked with an asterisk are required. Example: serial*.

Retrieve Layer 3 firewall rules for MX appliances

This endpoint returns the L3 firewall rules for an MX appliance.

Request

GET /networks/{networkId}/l3FirewallRules

Path parameter Type Description
networkId* string Network identity is a portion of the TCP/IP address that is used to identify individuals or devices on a network such as a local area network or the Internet.

Update firewall rules

Updates the L3 firewall rules of an MX network.

Request

PUT /networks/{networkId}/l3FirewallRules

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791
^^Request body example^^
[
    {
        "comment": "Allow TCP traffic to subnet with HTTP servers.",
        "policy": "allow",
        "protocol": "tcp",
        "destPort": 443,
        "destCidr": "192.168.1.0/24",
        "srcPort": "Any",
        "srcCidr": "Any",
        "syslogEnabled": false
    }
]
Body parameter Type Description
comment string Description of the rule (optional).
policy* string allow or deny traffic specified by this rule.
protocol* string The type of protocol (must be tcp, udp, icmp or any).
destPort* string allow or deny traffic specified by this rule.
destCidr* string Comma-separated list of destination IP address(es) (in IP or CIDR notation), fully-qualified domain names (FQDN) or any.
destPort* string Comma-separated list of destination port(s) (integer in the range 1-65535), or any.
srcCidr* string Comma-separated list of source IP address(es) (in IP or CIDR notation), or any. Note: FQDN not supported for source addresses.
srcPort* string Comma-separated list of source port(s) (integer in the range 1-65535), or any.
syslogEnabled boolean Log this rule to syslog (true or false, boolean value) - only applicable if a syslog has been configured (optional).

Response

^^Response example^^
Successful HTTP Status: 200
[
    {
        "comment": "Allow TCP traffic to subnet with HTTP servers.",
        "policy": "allow",
        "protocol": "tcp",
        "destPort": 443,
        "destCidr": "192.168.1.0/24",
        "srcPort": "Any",
        "srcCidr": "Any",
        "syslogEnabled": false
    }
]

Retrieve a list of switch ports

Lists the switch ports for a switch.

GET /devices/{serial}/switchPorts

See Retrieve a list of switch ports.

Retrieve a specific switch port

GET /devices/{serial}/switchPorts/{number}

See Retrieve a specific switch port.

Update a switch port

Updates a device switch port. Take the following notes into account:

  • Only access ports can be updated.
  • Only the subset of parameters listed below can be changed.
  • It's sufficient to only provide the parameters that you want to change in the payload.

Request

PUT /devices/{serial}/switchPorts/{number}

^^Request body example^^
{
    "enabled": true,
    "poeEnabled": true,
    "vlan": 10,
    "voiceVlan": 20,
    "accessPolicyNumber": "1234",
    "linkNegotiation": "Auto negotiate",
    "portScheduleId": "1234",
    "udld": "Alert only",
    "macWhitelist": [
        "34:56:fe:ce:8e:a0",
        "34:56:fe:ce:8e:a1"
    ],
    "stickyMacWhitelist": [
        "34:56:fe:ce:8e:b0",
        "34:56:fe:ce:8e:b1"
    ]
}
Body parameter Type Description
enabled boolean The status of the switch port.
poeEnabled boolean The Power over Ethernet (PoE) status of the switch port.
vlan integer Comma-separated list of destination port(s) (integer in the range 1-65535), or any.
voiceVlan integer The voice VLAN of the switch port. Only applicable to access ports.
accessPolicyNumber integer The number of the access policy of the switch port. Only applicable to access ports.
linkNegotiation string The link speed for the switch port.
portScheduleId string The ID of the port schedule. A value of null will clear the port schedule.
udld string The action to take when Unidirectional Link is detected (Alert only, Enforce). The default configuration is Alert only.
macWhitelist array Only devices with MAC addresses specified in this list will have access to this port. Up to 20 MAC addresses can be defined. To disable MAC whitelist, set accessPolicyNumber to null.
stickyMacWhitelist array The initial list of MAC addresses for stickyMacWhitelist. To reset thestickyMacWhitelist, set accessPolicyNumber to null.

Response

^^Response example^^
Successful HTTP Status: 200

{
    "number": 1,
    "name": "My switch port",
    "tags": "tag1 tag2",
    "enabled": true,
    "poeEnabled": true,
    "type": "access",
    "vlan": 10,
    "voiceVlan": 20,
    "isolationEnabled": false,
    "rstpEnabled": true,
    "stpGuard": "disabled",
    "accessPolicyNumber": "1234",
    "linkNegotiation": "Auto negotiate",
    "portScheduleId": "1234",
    "udld": "Alert only",
    "macWhitelist": [
        "34:56:fe:ce:8e:a0",
        "34:56:fe:ce:8e:a1"
    ],
    "stickyMacWhitelist": [
        "34:56:fe:ce:8e:b0",
        "34:56:fe:ce:8e:b1"
    ],
    "stickyMacWhitelistLimit": 5,
    "stormControlEnabled": true
}

Retrieve a list of Service Set Identifiers (SSID)

Returns a specific Service Set Identifier (SSID).

GET /networks/{networkId}/ssids

See Retrieve a list of Service Set Identifiers (SSID).

Retrieve a single SSID

Returns a specific Service Set Identifier (SSID).

GET /networks/{networkId}/ssids/{number}

See Retrieve a single SSID .

Update Network SSID

Updates your network Service Set Identifier (SSID).

Only the parameters listed below can be configured.

Request

PUT /networks/{networkId}/ssids/{number}

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791
number* string The number of the SSID instance.
^^Request body example^^
{
    "enabled": "true",
    "psk": "12345678ABCD"
}
Body parameter Type Description
enabled string Determines whether or not the SSID is enabled.
psk string The passkey for the SSID. This parameter is only valid if the authMode is psk.

Response

^^Response example^^
Successful HTTP Status: 200

{
    "number": 0,
    "name": "My SSID",
    "enabled": true,
    "splashPage": "Click-through splash page",
    "ssidAdminAccessible": false,
    "authMode": "8021x-radius",
    "encryptionMode": "wpa-eap",
    "wpaEncryptionMode": "WPA2 only",
    "radiusServers": [
        {
            "host": "0.0.0.0",
            "port": 3000
        }
    ],
    "radiusAccountingEnabled": false,
    "radiusEnabled": true,
    "radiusAttributeForGroupPolicies": "Filter-Id",
    "radiusFailoverPolicy": "null",
    "radiusLoadBalancingPolicy": "null",
    "ipAssignmentMode": "NAT mode",
    "adminSplashUrl": "http://example.com",
    "splashTimeout": "30 minutes",
    "walledGardenEnabled": true,
    "walledGardenRanges": "example.com",
    "minBitrate": 11,
    "bandSelection": "5 GHz band only",
    "perClientBandwidthLimitUp": 0,
    "perClientBandwidthLimitDown": 0,
    "visible": true,
    "availableOnAllAps": false,
    "availabilityTags": [ "test-tag" ]
}

Create Network VLAN

Request

POST /networks/{networkId}/vlans

Path parameter Type Description
networkId* string The network ID of the device. Example: L_1234567894811040791
^^Request body example^^
{
    "id": "1234",
    "name": "My VLAN",
    "subnet": "192.168.1.0/24",
    "applianceIp": "192.168.1.1",
    "groupPolicyId": "101"
}
Body parameter Type Description
id* string The VLAN ID of the new VLAN (must be between 1 and 4094).
name* string The name of the new VLAN.
subnet* string The subnet of the VLAN.
applianceIp* string The local IP of the appliance on the VLAN.
groupPolicyId* string The id of the desired group policy to apply to the VLAN.

Response

^^Response example^^
Successful HTTP Status: 200

{
    "id": "1234",
    "networkId": "N_24329156",
    "name": "My VLAN",
    "applianceIp": "192.168.1.1",
    "subnet": "192.168.1.0/24",
    "groupPolicyId": "101",
    "fixedIpAssignments": {},
    "reservedIpRanges": [],
    "dnsNameservers": "google_dns",
    "dhcpHandling": "Run a DHCP server",
    "dhcpLeaseTime": "1 day",
    "dhcpBootOptionsEnabled": false,
    "dhcpBootNextServer": null,
    "dhcpBootFilename": null,
    "dhcpOptions": []
}


List of API resources

Go to the interactive OpenAPI Specification (OAS) documentation on SwaggerHub to explore the SD-LAN SD-WAN Network API endpoints. See KPN SD-LAN SD-WAN Network APIs.

Each endpoint has a complete description of all the required parameters:

  • Bluetooth clients.
  • Bluetooth settings.
  • Camera quality retention profiles.
  • Cameras.
  • Clients.
  • Connectivity monitoring destinations.
  • Content filtering categories.
  • Content filtering rules.
  • Devices.
  • Events.
  • Firewalled services.
  • Floorplans.
  • Group policies.
  • HTTP servers.
  • Intrusion settings.
  • Link aggregations.
  • MG Cellular Gateway.
  • MR Wireless Network.
  • MX Appliances.
  • Malware settings.
  • Management interface settings.
  • Meraki auth users.
  • Named tag scope.
  • NetFlow settings.
  • Networks.
  • Organization.
  • Radio settings.
  • SNMP settings.
  • SSIDs.
  • Security events.
  • Splash login attempts.
  • Splash settings.
  • Switch ACLs.
  • Switch port schedules.
  • Switch ports.
  • Switch profiles.
  • Switch settings.
  • Switch stacks.
  • Traffic shaping.
  • Uplink settings.
  • VLANs.
  • Wireless settings.


Return codes

Code Description
200 Success.
201 Created.
202 Accepted.
302 Found. Link in location header.
400 Bad request.
401 Unauthorized.
403 Forbidden.
404 Not found.
405 Method not allowed.
412 Precondition failed.
429 Too many requests.
500 Internal server error.
502 Bad gateway.
503 Service unavailable.


HTTP response headers

The following tables display the standard response headers that are returned with each API response:

Standard response field name Description
sunset This field will be populated with the deprecation details. By default the value is n/a.
api-version Indicates the API version you have used.
quota-interval Used to specify an integer (for example, 1, 2, 5, 60, and so on) that will be paired with the quota-time-unit you specify (minute, hour, day, week, or month) to determine a time period during which the quota use is calculated.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-limit Number of API calls an user can make within a given time period.
If this limit is exceeded, the user will be throttled and API requests will fail.
quota-reset-UTC All quota times are set to the Coordinated Universal Time (UTC) time zone.
quota-time-unit Used to specify the unit of time applicable to the quota.
For example, an interval of 24 with a quota-time-unit of hour means that the quota will be calculated over the course of 24 hours.
quota-used Number of API calls made within the quota.
strict-transport-security The HTTP Strict-Transport-Security (HSTS) response header lets a web site tell browsers that it should only be accessed using HTTPS, instead of using HTTP. All present and future subdomains will be HTTPS for a maximum of 1 year and access is blocked to pages or sub domains that can only be served over HTTP including HSTS preload lists of web browsers.
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload.
Access control field name Description
access-control-allow-credentials Tells browsers whether to expose the response to frontend JavaScript samp when the request's credentials mode (Request.credentials) is include.
When a request's credentials mode (Request.credentials) is include, browsers will only expose the response to frontend JavaScript samp if the Access-Control-Allow-Credentials value is true. Boolean.
access-control-allow-origin Indicates whether the response can be shared with requesting samp from the given origin.
access-control-allow-headers Used in response to a pre-flight request which includes the Access-Control-Request-Headers to indicate which HTTP headers can be used during the actual request.
access-control-max-age Indicates how long the results of a pre-flight request (that is the information contained in the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers) can be cached.
access-control-allow-methods Indicates which HTTP methods are allowed on a particular endpoint for cross-origin requests.
For example: GET, PUT, POST, DELETE.
content-length The Content-Length entity header indicates the size of the entity-body, in bytes, sent to the recipient.
content-type The Content-Type entity header the client what the content type of the returned content actually is.

Mopinion feedback