API-Based Device Monitoring

Most devices in GridNMS are monitored over SNMP or SSH. Some devices — especially cloud-managed platforms — don’t expose either on your network at all; everything about them lives behind their vendor’s own web API instead. API-based monitoring lets GridNMS poll that API directly and bring the results in as regular metrics on a regular device, right alongside your SNMP and SSH gear.

The first supported integration is Cisco Meraki (the Dashboard API) — clients, uplink loss and latency, and wireless status, polled every 5 minutes.

A device monitored this way is a normal device in your inventory: it shows up in search, has a device detail page, and can be alerted on and included in reports like anything else. The only difference is how GridNMS talks to it.

How it fits together

Three pieces work together:

1. A monitoring pack provides the collectors (what to fetch, how often) and the charts. Cisco Meraki is a downloadable vendor pack bundle — install it from the Downloads page the same way as any other vendor pack (see Vendor packs). You don’t need to build anything for it.
2. An API credential holds the secret that authenticates to the vendor’s API (an API key, a bearer token, or a username/password). Credentials are stored separately from any single device so several devices — or every device in a class — can share one.
3. An API target points a class or a device at a base URL and a credential, and supplies any values the pack’s requests need filled in (like a device’s serial number). This is what actually turns polling on.

Step 1: Add an API credential

Go to Configure → API Credentials and add one:

• Ref — a short identifier other settings will reference (for example meraki-main). Letters, numbers, ., _, and - only.
• Name — an optional friendly label, e.g. “Meraki — main org.”
• Auth type — how the credential is sent:
  • API key (custom header) — the credential is sent as a named header. For Meraki, set the header name to X-Cisco-Meraki-API-Key.
  • Bearer token — sent as Authorization: Bearer <token>.
  • Basic auth — sent as a username and password.
• Secret / token (or Password for Basic auth) — the actual key or token.

The secret is encrypted at rest and is never shown again after you save it — editing a credential later shows a masked placeholder in its place, and saving without changing that field leaves the stored secret untouched.

A credential isn’t tied to one device. Reference the same Ref from as many class- or device-level API targets as you need.

Step 2: Point a class or device at the API

You can configure API monitoring at the class level (every device of that type shares the same base URL and credential) or at the device level (one device only, or an override for a single device in an otherwise class-configured group). Most Meraki setups only need the class level, with each device supplying its own serial number as a variable.

Class-level (recommended for most fleets)

Open Configure → Device Classes, select (or create) the class your Meraki devices belong to, and find the API Monitoring section:

1. Turn the section’s toggle on — this is what actually allows the class’s API target to be sent to a collector. Devices in a disabled class don’t get polled even if a target is configured underneath.
2. Set the Base URL — for Meraki this is your Dashboard API base, typically https://api.meraki.com/api/v1.
3. Choose the Credential you created in Step 1.
4. Optionally add template variables shared by every device in the class, for example orgId if your requests need your Meraki organization ID.

Every device in that class (and its subclasses) now inherits this base URL, credential, and shared variables.

Device-level

Open a device’s detail page and click API Monitoring. The panel shows:

• Effective from class — the base URL, credential, and variables the device is currently inheriting (read-only), if its class has API monitoring configured.
• Device override — settings for this device alone. Leave Base URL blank to keep inheriting the class’s base URL and credential, and use this panel only to supply the device’s own variables (most commonly its serial). Filling in a Base URL here fully overrides the class setting instead of inheriting it.

For Meraki, the device-level override is normally just one variable:

Variable	Value
serial	The device’s Meraki serial number, e.g. Q2XX-YYYY-ZZZZ

Template variables are substituted into the pack’s request URLs wherever they’re referenced — for example a request to /devices/{{serial}}/clients becomes /devices/Q2XX-YYYY-ZZZZ/clients for that device.

A device with no API target configured anywhere in its class hierarchy simply isn’t polled over the API — this doesn’t affect any SNMP/SSH monitoring already set up on it.

What you get

Once a device has an effective base URL, credential, and any required variables, its API pack collectors start polling on their normal interval. For Meraki that means:

• Clients — connected client count over time.
• Uplink — WAN uplink packet loss and latency.
• Wireless SSIDs — number of enabled SSIDs.

These appear as chart tabs on the device detail page, the same way SNMP-sourced metrics do, and the underlying values are available anywhere device metrics are — Metric Explorer, thresholds, and detections.

More integrations

Cisco Meraki is the first API integration GridNMS ships. If you need another cloud-managed platform monitored this way, reach out to support@gridnms.io.