Connecting to Meraki

Important security notice: Meraki has a security issue when you have access to more than one Meraki Organization. Because the API token is tied to a user account, and not to the accessed Meraki Organization, using your own personal API token is not appropriate.

For this reason, we strongly recommend that you create a dedicated "Magic Suite" user in your own domain (e.g. magicsuite@mymsp.com) and provide that user with access to only the required Meraki Organizations. The same Meraki user and key can then serve every Magic Suite app that needs Meraki data, whether that is ReportMagic, DataMagic, AlertMagic or ConnectMagic.

You will also need a Meraki API key for that user. This is generated in the Meraki Dashboard, not in Magic Suite. Sign in to the Meraki Dashboard as the dedicated user, then go to Organization, API & Webhooks, and the API keys and access tab. See Cisco's API key documentation for the current steps.

A Meraki API key is a 40-character lower case hexadecimal string. Magic Suite checks this when you save the Connection and refuses anything else, so if you are told the API key is invalid, check that you have pasted the whole key with no leading or trailing spaces.

Meraki Macros

ReportMagic has Meraki macros which provide information available via Meraki API calls. Connections themselves are set up in the Admin app and shared across Magic Suite.

To use [Meraki.XXX:] macros (such as the [Meraki.Query:] macro), set up a Meraki Connection as follows:

1. In the Admin app, go to the Connections page accessible via the menu
2. Click the Create button
3. From the Type drop-down, select a Connection type of Meraki
4. Enter a name - we recommend that you use "Default" for the name of the first connection of each type, and optionally, a description
5. In the URL field, enter the API URL, for example, https://api.meraki.com
6. In the API Key field, enter the Meraki API key that you want to use
7. If you need to provide advanced configuration, for example to specify a region or apply rate limiting, you can use the Configuration field. See below for examples
8. You can also click the Test Connection button in the form before saving, to check if it works
9. Click Save

Optional Configuration

You may enter additional configuration into the Configuration field. This is optional, and any items not set will cause the default values to be used.

The configuration must be entered as JSON (name and value pairs). The available options are:

• ApiRegion - this is the API region used when connecting to Meraki. Options are:
  • Canada
  • China
  • Default
  • Government
  • India
• ApiNode - no longer works. Do not use it. Cisco withdrew shard-direct API access in September 2025, so this setting has no effect and is ignored. If you have it in an existing Configuration, remove it. Earlier versions of this page recommended setting it; that advice was wrong once the Meraki change took effect, and following it does not prevent the HTTP not found (404) errors it used to be suggested for.
• BackOffDelayFactor - this is the exponential factor by which the API Retry-After duration is increased on each attempt, e.g. 1.0 = no change, 1.5 = 50% increase, 2.0 = double. [Default = 1.0, which means the back-off does not grow between attempts - see Retry behaviour below]
• HttpClientTimeoutSeconds - allows overriding the HTTP client timeout in seconds. This covers the whole attempt sequence for a single request, including every retry and every wait between retries, so it is the setting that ultimately puts a ceiling on how long one Meraki call can take. [Default = 600]
• MaxAttemptCount - this is how many times we will attempt to re-try requests to Meraki (e.g. upon any type of failure). [Default = 500] We recommend setting this to a much lower value, such as 5 or 10. See Retry behaviour below for why the default is rarely what you want.
• MaxBackOffDelaySeconds - when Meraki sends HTTP status code 429 (too many requests), Magic Suite waits before trying again, and that wait grows on each attempt according to BackOffDelayFactor. This option sets the maximum wait in seconds. [Default = 30]
• RateLimitMaxCalls - the maximum number of API calls to Meraki allowed in the specified time window (to use with RateLimitTimeSpanSeconds)
• RateLimitTimeSpanSeconds - the time window for the number of calls (to use with RateLimitMaxCalls)
• ReadOnly - when set to true, only HTTP GET requests can be sent to Meraki. When set to false, requests that make changes are allowed as well. If this property is omitted, the Connection's Read Only checkbox applies instead. See Read only Connections below

To use rate-limiting, both the parameters (RateLimitMaxCalls and RateLimitTimeSpanSeconds) must be set, or rate-limiting will not be applied. Setting only one of them has the same effect as setting neither. With no rate limit in force, reports and macros send Meraki calls as fast as they are able, with nothing pacing them, which makes hitting Meraki's rate limit far more likely. See Retry behaviour below.

Retry behaviour

When a Meraki call fails, Magic Suite may retry it. Understanding what is retried, and for how long, is usually the key to diagnosing a Meraki report that seems to hang.

What is retried:

• HTTP 429 (too many requests) - Magic Suite waits for the period Meraki asks for in its Retry-After response, or one second if Meraki does not specify one
• HTTP 502, 503 and 504 - a fixed five second wait
• A request that takes longer than 25 seconds to respond
• Network-level failures, such as the connection being reset or the Meraki endpoint being temporarily unreachable

What is not retried - these fail immediately, which is deliberate, because retrying cannot help:

• HTTP 401 and 403 - the API key is wrong, has been revoked, or does not have access to that Meraki Organization
• HTTP 404 - the object does not exist
• HTTP 500, and any other status not listed as retried above

Why the default MaxAttemptCount of 500 is rarely what you want. The wait between retries grows according to BackOffDelayFactor, but that setting defaults to 1.0, which means "no change" - so out of the box the wait does not actually grow at all, and each attempt simply waits about a second. Five hundred attempts a second apart cannot finish inside the ten minute HttpClientTimeoutSeconds ceiling, so in practice a persistently throttled call runs until that timeout rather than until it runs out of attempts. A single Meraki call can therefore occupy up to ten minutes of a report job.

If a Meraki report is slow or appears to hang, this is the usual cause. Setting MaxAttemptCount to 5 or 10 makes the connection give up promptly and report a clear error instead.

Raising MaxAttemptCount is usually the wrong response to seeing 429 errors. Meraki allows roughly five requests per second per Organization. Retrying harder against a limit you are already exceeding adds to the pressure and can starve your other tools that share the same API key. Setting RateLimitMaxCalls and RateLimitTimeSpanSeconds so that Magic Suite stays under the limit in the first place is almost always the better fix.

Which settings apply where

Not every part of Magic Suite uses all of these settings.

• Reports and macros use the Connection's Configuration exactly as you set it. Anything you leave out takes the default shown above, so leaving MaxAttemptCount and the rate limit unset means 500 attempts and no pacing.
• DataMagic collection applies its own attempt count and back-off, and ignores MaxAttemptCount and BackOffDelayFactor. It does use your ApiRegion, and it does use your rate limit if you have set one, defaulting to five calls per second if you have not. Setting MaxAttemptCount on a Connection that is only used by DataMagic will therefore appear to have no effect, which is expected.
• Background connection checks, such as the periodic connection status and statistics polling, default to ten attempts and five calls per second unless your Configuration specifies otherwise.

There is one further setting, the per-attempt timeout of 25 seconds mentioned above. It is fixed and cannot be changed in a Connection's Configuration.

Read only Connections

A Meraki Connection has two separate settings that control whether Magic Suite is allowed to make changes in Meraki:

• The Read Only checkbox on the Connection itself. This applies to every type of Connection, and is ticked by default on a new Connection
• An optional ReadOnly property inside the Configuration field, which applies to Meraki Connections only

If the Configuration contains a ReadOnly property set to true or false, that decides it. If it does not, the Read Only checkbox decides it:

• Read Only ticked, no ReadOnly property in the Configuration - the Connection can only read
• Read Only not ticked, no ReadOnly property in the Configuration - the Connection can read and make changes
• Read Only ticked, Configuration sets ReadOnly to false - the Connection can read and make changes
• Read Only not ticked, Configuration sets ReadOnly to true - the Connection can only read

Because the Read Only checkbox is ticked by default, a new Meraki Connection cannot make changes until you either clear that checkbox, or set "ReadOnly": false in the Configuration. This matters for the Meraki Webhooks page in AlertMagic, which needs to make changes to create Webhooks.

The ReadOnly property is only used when its value is exactly true or false. If it is written as text (for example "true" in quotes), spelled with different capitalisation (for example readOnly), or the Configuration is not valid JSON, then the property is ignored and the Read Only checkbox applies instead.

(Coming in version 4.5) Where the Configuration overrides the checkbox, the Connections list in the Admin app shows this in the Read Only column, for example "True, but writable", with a tooltip naming both settings and explaining what the Connection actually does.

Configuration Examples

Example 1

This example uses the China region, and ensures that Meraki DataMagic makes no more than 100 calls within 60 seconds.

{
    "ApiRegion": "China",
    "RateLimitMaxCalls": 100,
    "RateLimitTimeSpanSeconds" : 60
}

Example 2

This example customises the retry and back-off properties, and also allows HTTP requests that update items (such as creating Webhooks) by setting "ReadOnly" to false.

Note the two settings that work together: MaxAttemptCount of 10 gives up promptly rather than retrying hundreds of times, and BackOffDelayFactor of 1.5 makes each wait 50% longer than the last, up to the 60 second ceiling. The rate limit of 5 calls per second matches Meraki's own per-Organization limit.

{
    "ApiRegion": "Default",
    "BackOffDelayFactor": 1.5,
    "HttpClientTimeoutSeconds": 600,
    "MaxAttemptCount": 10,
    "MaxBackOffDelaySeconds": 60,
    "RateLimitMaxCalls": 5,
    "RateLimitTimeSpanSeconds": 1,
    "ReadOnly": false
}

Example 3

If you are unsure what to use, this is a sensible starting point for any Meraki Connection. It keeps Magic Suite within Meraki's per-Organization rate limit and makes a failing call give up in a reasonable time instead of retrying for several minutes.

{
    "MaxAttemptCount": 10,
    "BackOffDelayFactor": 1.5,
    "RateLimitMaxCalls": 5,
    "RateLimitTimeSpanSeconds": 1
}