Cisco Meraki Add-on for Splunk

API Key

1. In the Meraki Dashboard, navigate to Organization ▸ API & Webhooks
2. Generate an API key (or reuse an existing key with appropriate read permissions)
3. Store the key securely; it is shown only once
4. Ensure API access is enabled for the organization

Organization ID

You will need your Meraki organization ID for configuration.

From the Dashboard footer: The organization ID appears in the footer when viewing an organization.

From the API:

• Open https://api.meraki.com/api/v1/organizations in a browser while logged in, or
• Use cURL:

curl -L --request GET \
  --url https://api.meraki.com/api/v1/organizations \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <API_KEY>'

Device Configuration

For clearer dashboards and searches:

• Name devices (access points, cameras, security appliances, switches, sensors) consistently in the Meraki Dashboard
• Use naming conventions that include location, role, and site as needed

(Optional) Change logging level

1. Go to the Configuration tab
2. Click the Logging tab
3. Select a new logging level from the drop-down menu
4. Click Save

(Optional) Proxy setup

1. Go to the Configuration tab
2. Click the Proxy tab
3. Check Enable and fill in the required fields

What You Need

• A Meraki OAuth application registered at https://integrate.cisco.com
• The application Client ID and Client secret
• The OAuth scopes required for the inputs you plan to enable (see the OAuth Scopes column in the Inputs and API reference table)
• The redirect URI (shown by the add-on in Configuration ▸ Organization when you select OAuth)

Steps to Configure OAuth

1. Register the integration at https://integrate.cisco.com and select the required scopes
2. In Configuration ▸ Organization for your Splunk organization record:
   • Choose OAuth
   • Enter the Client ID and Client secret
3. Use the add-on's Connect/Authorize action to complete the admin grant

Once configured, new and existing inputs for that organization will use OAuth tokens instead of the API key.

Note: Ensure the OAuth Web App has been granted all necessary scopes before configuring inputs. If an input requires a scope not granted, the input will receive 403 Forbidden errors.

Manage Inputs

1. In Splunk Web, open Cisco Meraki Add-on for Splunk ▸ Inputs
2. Click Create New Input
3. Select the desired input type
4. Fill required fields:
   • Name: A unique, descriptive input name
   • Organization: Select the configured organization
   • Interval: Polling interval in seconds
   • Start From (if applicable): Begin polling from N days in the past
   • Top Count (if applicable): Number of top records to retrieve
   • Index: Target index for the data
5. Click Save

To manage existing inputs:

• Disable / enable: Toggle the status in Inputs
• Edit: Use Action ▸ Edit to change schedule, index, or organization
• Clone / delete: Use Action ▸ Clone/Delete as needed

Pre-upgrade Steps

1. Back up your existing configuration
2. Document all configured inputs and organizations
3. Note any custom macros or field extractions

Post-upgrade Configuration

1. Reconfigure organizations in the new Organization page
2. Re-create inputs using the new input creation workflow
3. Update macros to reflect new index configurations if needed
4. Test webhook configurations

Verification Steps

1. Verify data is being collected: index=* sourcetype="meraki:*" | stats count by sourcetype
2. Check add-on logs: index="_internal" source="*splunk_ta_cisco_meraki*.log*"
3. Confirm webhooks are working: index=* sourcetype="meraki:webhook"

Generate a HEC token

1. In Splunk Web, go to Settings ▸ Data Inputs ▸ HTTP Event Collector
2. Ensure HEC is enabled and note the HTTP port (default 8088)
3. Create a new token:
   • Name: For example, Meraki Webhook
   • Sourcetype: meraki:webhook
   • Index: Target index for webhook data
4. Save and copy the token value

On Meraki Platform

Use the Meraki Dashboard webhook test feature to send a test alert.

On Splunk Platform

Search for webhook events:

index=<WEBHOOK_INDEX> sourcetype="meraki:webhook"

Configuring Macros

You can modify macros in Splunk by following these steps:

1. Navigate to Settings > Advanced Search > Search macros

   
   

2. Once the macros page opens:

   • Go to the apps dropdown
   • Select "Cisco Meraki Add-on for Splunk"
   • This shows the list of macros created for Cisco Meraki
   

3. To edit a macro:

   • Click on the name of the macro to open the editing window
   • If you have a separate index for your data collection, you can update the macro definition to add support for that index
   • By default the supported index is main
   • To add more indexes, add a comma(,) and the index name you want to add

Example:

index IN( main , test_index )

Pattern 1

Time series, historical APIs

Pattern 2

Current state / inventory APIs

Pattern 3

Top‑N summary APIs

API Connectivity

Test API key or OAuth access:

curl -L -X GET \
  'https://api.meraki.com/api/v1/organizations' \
  -H 'Authorization: Bearer <API_KEY_OR_TOKEN>'

You should receive a list of organizations. If you see 403 or 404, verify API access, credentials, and scopes.

Check add-on logs

index="_internal" source="*splunk_ta_cisco_meraki*.log*"

Filter for ERROR to identify configuration or connectivity problems.

Authentication Issues

• 401 Unauthorized:
  • API Key: Verify the API key is correct and has not been revoked in the Meraki Dashboard
  • OAuth: Access token may be expired. Check if automatic token refresh is working by reviewing logs for "Token refresh" messages
  • New API key/org: If the key or organization was just created, wait 1-2 minutes for API propagation
• 403 Forbidden:
  • Insufficient permissions: API key must have organization-level read access
  • OAuth scopes missing: If using OAuth, verify the Web App has been granted the required scopes (not just offline_access). Check logs for "No scopes are granted to the Meraki Web App"
  • IP whitelist: If the API key has IP restrictions configured in Meraki Dashboard, ensure the Splunk server IP is whitelisted
• OAuth token refresh failures:
  • Verify client_id and client_secret match the Meraki Web App configuration
  • Check if the refresh token has been revoked in the Meraki Dashboard
  • Confirm the authorization endpoint is correct (default: as.meraki.com)
  • Review splunk_ta_cisco_meraki_rh_oauth2_token logs for token fetch errors

Rate Limiting (429 Too Many Requests)

• Reduce API call rate: Lower the Max API calls per second setting in the organization configuration (default: 5 calls/sec)
• Stagger inputs: If multiple inputs are configured for the same organization, adjust their schedules to avoid simultaneous execution
• Monitor rate limiter: Check logs for "Rate limit exceeded" warnings. The add-on automatically waits 30 seconds before retrying
• Review concurrent inputs: Multiple Splunk instances collecting from the same org can exceed combined rate limits

Data Collection Issues

• No data ingested:
  • Verify credentials are valid using the API connectivity test above
  • Confirm the organization ID is correct and accessible
  • Verify the correct Service Region is selected and Base URL matches your Meraki region
  • Ensure inputs are enabled in the inputs configuration
  • Check the target index exists and is searchable
  • Review input logs for errors: index="_internal" source="*[input_name]*"
• Missing historical data:
  • Check the Start from days ago parameter for time-series inputs
  • Verify the requested time range is within Meraki's data retention limits (varies by data type, typically 30-90 days)
  • Review checkpoint data to see when the last successful collection occurred
• Data collection stopped:
  • Check for checkpoint retrieval failures in logs: "Could not retrieve checkpoint"
  • Verify KVStore is accessible and healthy
  • Confirm the input schedule hasn't been disabled

Webhook Issues

• Webhook validation fails:
  • HTTPS required: HEC webhook URL must use HTTPS (not HTTP)
  • Valid SSL certificate: The Splunk server must have a verified SSL certificate. Self-signed certificates may cause validation failures
  • Error message: "The URL should be using https and have verified SSL certificate"
• Webhook not receiving events:
  • Confirm HEC is enabled in Splunk: Settings > Data inputs > HTTP Event Collector
  • Verify the HEC token is valid and not disabled
  • Check webhook logs via the meraki:webhooklogs:api input to see delivery status and response codes
  • Test webhook connectivity from Meraki Dashboard
• Webhook setup hangs:
  • If webhook test status remains "enqueued", check network connectivity between Meraki and Splunk
  • Review firewall rules to ensure Meraki can reach the Splunk HEC endpoint
  • Verify HEC port (default: 8088) is open and accessible

Regional Connectivity Issues

• 404 Not Found on all API calls:
  • For China deployments, ensure China region is selected (uses api.meraki.cn)
  • For FedRAMP/US Government, ensure FedRAMP region is selected (uses api.gov-meraki.com)
  • For India deployments, ensure India region is selected (uses api.meraki.in)
  • For Canada deployments, ensure Canada region is selected (uses api.meraki.ca)
  • For proxy deployments, use Other region and enter your custom proxy URL in the Base URL field
• Network timeouts:
  • Check if a proxy is required for external API access
  • Verify DNS resolution for the Meraki API endpoint
  • Test connectivity using curl from the Splunk server

Proxy Configuration Issues

• Proxy validation errors:
  • If proxy is enabled, both Proxy URL and Proxy Port are required
  • Proxy port must be between 1-65535
  • If proxy requires authentication, both username and password must be provided (not just one)
• Connection failures through proxy:
  • Verify proxy credentials are correct
  • Test proxy connectivity manually using curl with proxy settings
  • Check if the proxy requires special SSL/TLS handling
  • Review proxy logs for blocked or failed requests

Checkpoint/State Management Issues

• Checkpoint retrieval failures:
  • Error: "Could not retrieve checkpoint. Not collecting events."
  • Verify KVStore is running and accessible: $SPLUNK_HOME/bin/splunk show kvstore-status
  • Check session key validity in logs
  • Review splunk_ta_cisco_meraki logs for "Error in Checkpoint handling"
• Duplicate data collection:
  • May occur if checkpoint is not being saved properly
  • Check KVStore write permissions for the add-on
  • Verify sufficient disk space for KVStore data
• Data gaps after restart:
  • Checkpoint may not have been saved before restart
  • Use Start from days ago parameter to backfill missed data

Input Configuration Issues

• Input won't start:
  • Invalid interval: Must be an integer within the allowed range for that input type
  • Invalid start_from_days_ago: Must be an integer if specified, within historical data retention limits
  • Invalid top_count: For "top N" inputs, must be an integer within valid range
  • Review splunk_ta_cisco_meraki_*_validation logs for validation errors
• KeyError in logs:
  • Missing required configuration parameter
  • Organization name not found in configuration
  • Verify organization is configured and saved before creating inputs