Guide: User agents developers must send unique user agent strings with every API request. In this guide, the basics of formatting and implementation are described.

User agents

When you invoke dashboard API, it's best practice to provide a custom user agent string with each API request. This helps your customers and Meraki administrators monitor API interactions with their environments and helps build their trust. In brief, here are some Dos and Don'ts with user agent strings.

Dos

  1. Provide the user agent string in the user agent header of every API request.
  2. Follow the prescribed format below, which differs minimally from standard practices.
  3. Include only the requested information in your user agent string.
  4. Use only slashes (/) when you optionally provide application version information.

Don'ts

  1. Do not provide inconsistent or incorrect user agent strings across your application.
  2. Do not omit the user agent string from any of your requests.
  3. Do not add unnecessary information or special characters to your user agent string.
  4. Do not mix the forward slash (/) with the backward slash (\).

Formatting

Format your user agent strings as follows:

ApplicationName VendorName

Include version information as follows:

ApplicationName/1.0 VendorName

Regardless of your branding guidelines, your application name and vendor name must omit all spaces, hyphens, and special characters. When you provide a custom user agent string in API calls, ensure that the information is typically exclusively useful to Meraki dashboard admins, so it's not necessary to include sometimes arcane information, as is common practice amongst web browsers.

Examples

Example 1

If your vendor name is Lunar Commander, and your application name is Planet Craft Lite, then use:

PlanetCraftLite LunarCommander

or, if you want to include a version string:

PlanetCraftLite/0.8b LunarCommander

Example 2: Hyphenated names

If your vendor name is Happy-Rabbit Productions, and your application name is Burrow Finder, then use: 

BurrowFinder HappyRabbitProductions

or, if you want to include a version string:

BurrowFinder/2.5 HappyRabbitProductions

In practice

It's usually trivial to add user agent headers to your API requests. All HTTP request libraries offer some means of appending the user agent header to your requests.

Python library

If you use the Meraki Python library, then simply pass the kwarg caller in your session definition.

import meraki
dashboard = meraki.DashboardAPI(caller='PlanetCraftLite/0.8b LunarCommander')

Alternatively, you can modify the library's config.py file to set this globally. For more information, see Official Dashboard API library (SDK) for Python

PowerShell

If you use the Invoke-WebRequest method, then provide the -UserAgent flag in each of your requests:

$userAgent = 'ApplicationName VendorName'
$apiCallExample = Invoke-WebRequest -URI $uri -Headers $headers -UserAgent $userAgent

Java

If you use the HttpURLConnection module, then use setRequestProperty to send the user agent:

import java.net.HttpURLConnection;
String userAgent = "ApplicationName VendorName"

HttpURLConnection connectionExample = null;
urlExample = new URL(exampleStringUrl); // appropriate operation URL here
connection = (HttpURLConnection) urlExample.openConnection();
// other setRequestProperties here, e.g. Bearer Auth, etc.
connection.setRequestProperty("User-Agent", userAgent);