Guide: User Agents Developers should send unique user agent strings with every API request. In this guide, we cover the basics of formatting and implementation.

User agents

When invoking dashboard API, it's best practice to provide a custom user agent string with each API request. This helps your customers and Meraki admins 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. Only use slashes ("/") when optionally providing application version information.

Don'ts

  1. Provide inconsistent or incorrect user agent strings across your application.
  2. Leave out the user agent string from any of your requests.
  3. Add unnecessary information or special characters to your user agent string.
  4. Mix up slashes (e.g. "/") and backslashes (e.g. "\").

Formatting

Please format your user agent strings accordingly:

ApplicationName VendorName

If you want to include version information, do so as follows:

ApplicationName/1.0 VendorName

Regardless of your branding guidelines, your application name and vendor name must omit all spaces, hypens, and special characters. When providing a custom user agent string in API calls, keep in mind that the information is typically exclusively valuable 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 requests libraries offer some means of appending the User-Agent header to your requests.

Python library

If using 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. Consult the docs for more information.

PowerShell

If using 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 using 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);