Home > General Administration > Other Topics > The Cisco Meraki Dashboard API

The Cisco Meraki Dashboard API

Overview

The Cisco Meraki Dashboard API is a modern, RESTful API using HTTPS for transport and JSON for object serialization. It is similar to other modern web APIs such at Github’s, Stripe’s, and Trello’s. Support for other protocols, if required, can be provided by an adaptor on the client side. Cisco Meraki does not plan to build any such adaptors. For access to the API, first enable the API for your organization under Organization > Settings > Dashboard API access.  

Detailed online documentation that is automatically kept up-to-date can be found by logging into Dashboard and going to Help > API docs, or it can be viewed on the public page here.

 

After enabling the API, go to the my profile page to generate an API key. The API key is associated with a Dashboard administrator account. You can generate, revoke, and regenerate your API key on your profile.

Keep your API key safe as it provides authentication to all of your organizations with the API enabled. If your API key is shared, you can regenerate your API key at any time. This will revoke the existing API key.

What can Dashboard API be used for?

The dashboard API can be used for many purposes. It's meant to be an open-ended tool. Here are some examples of use cases:

 

  • Add new organizations, admins, networks, devices, VLANs, and more
  • Configure 1800 networks in 9 minutes with just a few API calls
  • Automatically on-board and off-board new employees' teleworker setup
  • Build your own dashboard for store managers, field techs, or unique use cases

Requirements

Every request must specify an API key via a request header

 

The API key must be specified in the URL. The API will return 404 (rather than a 403) in response to a request with a missing or incorrect API key in order to prevent leaking the existence of resources to unauthorized users.

X-Cisco-Meraki-API-Key: <secret key>

The API version must be specified in the URL:

https://dashboard.meraki.com/api/v0/<resource>

Once an API version is released, we will make only backwards-compatible changes to it. Backwards-compatible changes include:

  • Adding new API resources
  • Adding new optional request parameters to existing API methods

  • Adding new properties to existing API responses

  • Changing the order of properties in existing API responses

Identifiers in the API are opaque strings. A <network_id>, for example, might be the string “126043”, whereas an <order_id> might contain characters, such as “4S1234567”. Client applications must not try to parse them as numbers. Even identifiers that look like numbers might be too long to encode without loss of precision in Javascript, where the only numeric type is IEEE 754 floating point.

 

Verbs in the API follow the usual REST conventions: GET returns the value of a resource or a list of resources, depending on whether an identifier is specified. For example, a GET of /v0/organizations returns a list of organizations, whereas a GET of /v0/organizations/<org_id> returns a particular organization. POST adds a new resource, as in a POST to /v0/organizations/<org_id>/admins, or performs some other non-idempotent change. PUT updates a resource. PUTs are idempotent; they update a resource, creating it first if it does not already exist. A PUT should specify all the fields of a resource; the API will revert omitted fields to their default value. DELETE removes a resource. Call volume is limited to 5 calls per second (per organization).

Status and error codes

 

Responses from the API generally use standard HTTP status codes. Some examples:

  • 400: Bad Request- You did something wrong, e.g. a malformed request or missing parameter.
  • 403: Forbidden- You don't have permission to do that.
  • 404: Not found- No such URL, or you don't have access to the API or organization at all.

If the response code is not specific enough to determine the cause of the issue, error messages will be included in the response in JSON format, for example:

{
    "errors": [
       "VLANs are not enabled for this network"
    ]
}

Examples

 

Example requests and responses follow. Please note that these are not comprehensive; for a comprehensive list of API endpoints and their details, please see the online documentation URL above.

Organizations

 

Retrieve the list of organizations for the API key specified in X-Cisco-Meraki-API-Key:

GET https://dashboard.meraki.com/api/v0/organizations
Response code: 302
Response: redirect to https://n123.meraki.com/api/v0/organizations

Note that the request is redirected to n123.meraki.com. A 302 may happen on any API call, including those that modify state such as DELETE, POST, and PUT. When a GET is redirected, the status code will be 302. When a non-GET is redirected, the status code will be 307 for Postman, or 308 for any other client. Client applications must follow these redirects. No action will be taken by the host issuing the redirect, so even non-idempotent requests are safe to retry on the new host.

Query sent to the redirect link:

GET https://n123.meraki.com/api/v0/organizations
Response code: 200
Response body: [ {“id”: <org_id>, “name”: “Test Organization” } ]

Retrieve metadata about a specific organization:

GET https://dashboard.meraki.com/api/v0/organizations/<org_id>
Response code: 200
Response body: { "id": <org_id>, "name": "Test Organization" }

Note also that most HTTP libraries and clients will not follow a redirect with an HTTP verb other than GET, and may instead follow the redirect but substitute GET for the HTTP verb. As a result, you may find a redirect on DELETE, POST, or PUT will look as though a GET was requested. To avoid this, first perform a GET on the organization you are working with, and store the URL you are working with, then use that URL for subsequent requests (particularly those that modify state).

 

Create a new organization:

POST https://n123.meraki.com/api/v0/organizations
Request body: { “name”: “Second Test Organization” }
Response code: 201 
Response body: { "id": <new_org_id>, name: "Second Test Organization" }

The new organization will be unconfigured with the exception that the admin who created it will have full organization write access on the new organization. Clients of the API can add additional admins and then remove the creating admin from the new organization if desired.

Note: The API will not allow clients to remove the last admin with full organization write access, however, as doing so could lead to an unconfigurable organization.

Networks

List the networks in an organization: 

GET https://n123.meraki.com/api/v0/organizations/<new_org_id>/networks
Response code: 200
Response body: [ { "id": <network_id>, "name": "Test Network", "organization_id": <new_org_id>, "type": "wireless",
   "timeZone": "America/Los_Angeles", "tags": " test "
} ]

Create a new network:

POST https://n123.meraki.com/api/v0/organizations/<org_id>/networks
Request body: { “name”: “Test Network 2”, “organizationId”: <org_id>, “type”: “appliance”}
Response code: 201
Response body: { “id”: <network_id>, “name”: “Test Network 2”, “organization_id”: <org_id>, “type”: “appliance”, “tags”: null }

Valid network types are “appliance”, “switch”, and “wireless”.

Licenses and Devices

 

Claim a device, license key, or order into an organization. When claiming by order, all devices and licenses in the order will be claimed; licenses will be added to the organization and devices will be placed in the organization's inventory. These three types of claims are mutually exclusive and cannot be performed in one request.

 

The “licenseMode” param can be either "renew" or "addDevices". "addDevices" will increase the license limit, while "renew" will extend the amount of time until expiration. This parameter is required when claiming by licenseKey. Please see this article for more information.

POST https://n123.meraki.com/api/v0/organizations/<org_id>/ claim
Request body: { "order": "4CXXXXXXX" }
Response code: 200
Response body: <empty>
SNMP Settings

Set the SNMP settings for an organization. Note that the community string for SNMPv2 is in the response. It can also be retrieved via a get to this same URL.

GET https://n123.meraki.com/api/v0/organizations/<org_id>/snmp
Request body: { "v2cEnabled": true, "v3Enabled": true, "v3AuthMode": "SHA", "v3AuthPass", <secret>, "v3PrivMode": "AES128", "v3PrivPass": <secret>, "allowedIPs": ["5.6.7.8"] }
Response code: 200
Response body: { "v2Enabled": true, “v2CommunityString”: <secret>, "v3Enabled": true, "authMode": "SHA", "authPass", <secret>, "privMode": "AES128", "privPass": <secret>, "allowedIPs": ["5.6.7.8"] }
Administrators 

List the administrators for an organization:

GET https://n123.meraki.com/api/v0/organizations/<org_id>/admins
Response code: 200
Response body: [ { "name": "Jane Doe", "email": "jane@doe.com", "orgAccess": "full","id": <admin_id> } ]

Organization access can be “full”, “read-only”, or “none”.
 

Add a new administrator with rights to only one network:

POST https://n123.meraki.com/api/v0/organizations/<org_id>/admins/
Request body: { "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }
Response code: 201
Response body: { “id”: <admin_id>, "name": "John Doe", "email": "john@doe.com", "orgAccess": "none", "networks": [{ "id": <network_id>, "access": "full" }]

Valid access levels for networks are “full”, “read-only”, “monitor-only”, and “guest-ambassador”. Clients can also give administrators access by tag by substituting the “networks” field for “tags” such as:

"tags": [{ "tag": "foo", "access": "read-only" }],

Valid access levels for tags are the same as for networks. Clients can update administrators using PUT and specifying an admin_id.

Delete an administrator:

DELETE https://n123.meraki.com/api/v0/organizations/<org_id>/admins/<admin_id>
Response code: 204
Response body: <empty>
You must to post a comment.
Last modified
13:14, 29 Sep 2017

Tags

Classifications

This page has no classifications.

Article ID

ID: 4631

Contact Support

Most questions can be answered by reviewing our documentation, but if you need more help, Cisco Meraki Support is ready to work with you.

Open a Case

Ask the Community

In the Meraki Community, you can find answers provided by fellow Meraki users and ask questions of your own.

Visit the Community