This article provides guidance for building large-scale integrations with the Auvik API, including integrations that enrich or forward monitoring data to Cortex XSIAM.
API key creation, role assignment, tenant authorization, and Cortex XSIAM configuration require appropriate administrator or integration-development access.
For authentication, regional endpoints, API permissions, request formats, and general error handling, see Auvik API Integration Guide.
Rate limits and scaling
Auvik API requests are limited to approximately 2,500 requests per five-minute period per source IP. Design polling schedules and concurrency limits so the integration remains below this threshold.
Recommended practices:
- Batch and paginate large responses instead of requesting entire datasets repeatedly.
- Stagger polling jobs across tenants and data types.
- Use incremental or modified-since filters where the endpoint supports them.
- Request only the fields and records required by the integration.
- Implement exponential backoff for HTTP 429 and temporary 5xx responses.
- Honor the Retry-After header when it is returned.
- Do not repeatedly retry authentication, authorization, malformed-request, or not-found errors without first correcting the underlying issue.
- Track request volume and maintain sufficient headroom below the rate limit.
For multi-tenant integrations, calculate request volume across all tenants, polling categories, retries, and concurrent workers.
Endpoint selection
Select endpoints based on the data required by the integration rather than polling every available data source at the same frequency.
Tenant and site scope
- Identify the tenants or sites available to the API user before starting tenant-scoped collection.
- Preserve tenant and site identifiers throughout the integration.
- Process tenant-scoped requests separately so data from different customers cannot be mixed.
Device and inventory data
- Use the appropriate inventory endpoints for devices, interfaces, networks, VLANs, and related objects.
- Use modified-since, created-since, or equivalent incremental filters only where the endpoint documentation confirms they are supported.
- Use stable object identifiers and update timestamps to detect changes.
- Avoid repeatedly downloading complete inventory records when only a small number of objects have changed.
Statistics and health data
- Use the statistics endpoint and metric identifier documented for the specific data type.
- Request only the required time window and granularity.
- Use shorter incremental windows for high-priority metrics and longer windows for lower-priority data.
- Avoid overlapping time windows unless the integration deduplicates records safely.
Topology and relationships
- Retrieve neighbor, link, interface, and relationship data only when those relationships are exposed by the applicable API.
- Build relationships using stable device and interface identifiers.
- Do not assume that every device-to-switch, site, or subnet relationship is available in every environment.
- Plan a fallback behavior when the API does not expose a relationship required by the downstream system.
Suggested polling intervals
The following are starting points. Adjust them based on tenant size, API availability, rate limits, and the required data freshness.
- Device, interface, VLAN, and inventory data: every 15–30 minutes
- High-signal statistics or health metrics: every 1–5 minutes
- Lower-priority statistics: every 5–15 minutes
- Topology and relationship data: every 15–60 minutes
These intervals are not product requirements. A single large tenant or a large number of tenants may require slower polling or more aggressive incremental filtering.
Cortex XSIAM enrichment practices
Identity and scope
- Preserve the Auvik tenant ID, site ID, device ID, and interface ID as first-class identifiers.
- Never join records from different tenants solely by hostname, IP address, or MAC address.
- Include the tenant and site context in records sent to Cortex XSIAM.
Normalization
Normalize values before enrichment or ingestion:
- MAC addresses
- IPv4 and IPv6 addresses
- Hostnames
- Interface names
- Device types and vendor names
- Timestamps and time zones
Deduplication and state
- Maintain a state store containing previously seen object IDs and update timestamps.
- Use upsert operations instead of creating a new asset for every polling result.
- Preserve the source identifier used to determine whether a record is new, changed, or unchanged.
- Deduplicate overlapping statistics windows and repeated alert or state events before ingestion.
Data minimization
- Export only the fields required for detection, investigation, or enrichment.
- Avoid forwarding complete historical datasets when the downstream use case only requires recent changes.
- Remove unnecessary sensitive or operational data before sending records to Cortex XSIAM.
Reliability
- Use a queue or message bus between API collection and data transformation where appropriate.
- Make writes to Cortex XSIAM idempotent so retries do not create duplicate records.
- Isolate failures by tenant and job type so one failing tenant does not stop collection for all tenants.
Reference architecture
A scalable integration commonly includes the following components:
- Scheduler
Creates tenant- and data-type-specific jobs while enforcing concurrency and rate limits. - API client or poller
Calls the appropriate Auvik API endpoints, handles pagination, and applies retry and backoff logic. - Queue or message bus
Buffers raw API responses and separates collection from transformation. - Transformer and normalizer
Converts API responses into the required Cortex XSIAM format and applies identity normalization. - State store
Tracks object IDs, timestamps, deduplication state, and the last successful collection for each tenant. - XSIAM loader
Sends normalized data using idempotent writes and records ingestion results. - Observability layer
Tracks request volume, response codes, latency, queue depth, processing lag, and tenant-level failures.
Monitoring the integration
Monitor at least the following:
- Requests per five-minute window
- HTTP 429 responses
- HTTP 4xx and 5xx responses
- API latency
- Pagination failures
- Last successful poll by tenant and data type
- Queue depth and processing lag
- Number of records collected and loaded
- Duplicate or rejected records in Cortex XSIAM
Create operational alerts when the integration approaches its request budget, stops receiving data for a tenant, or develops an unacceptable processing backlog.
Known limitations
- API relationships and filters are not available for every endpoint or environment.
- Some data is product-specific and may require the correct API family, such as ASM or Unified Network Management.
- Required data may depend on the entitlements enabled for the tenant.
- An HTTP 200 response with an empty result does not necessarily indicate an API failure; the scope, filters, or time window may simply return no records.
- Endpoint schemas can change. Validate field names and relationships against the current API documentation before deploying changes.
Troubleshooting common issues
HTTP 308
A redirect may indicate that the integration is using the wrong regional API endpoint. Confirm the region-specific Auvik API base URL.
HTTP 401
Check the API username, API key, authentication method, and token or key status.
HTTP 403
Confirm that the API user is authorized for the requested tenant and has the permissions required by the endpoint.
HTTP 429
Reduce request concurrency, increase polling intervals, use incremental filters, and implement exponential backoff. Check whether multiple integrations are sharing the same source IP.
HTTP 5xx
Retry temporary server errors using exponential backoff. If errors continue, record the endpoint, timestamp, response status, and request correlation information before contacting Support.
Unexpected or empty results
Check the tenant scope, site filters, time range, pagination parameters, API family, and permissions. Confirm that the endpoint supports the filter or relationship being requested.