Auvik API Patterns

Auvik MCP Tools and API Patterns

Overview

The Auvik MCP server wraps the Auvik REST API (https://auvikapi.{region}.my.auvik.com/v1 and /v2) and exposes tools across tenants, devices, networks, interfaces, configurations, alerts, statistics, and billing. Two quirks to know up front: Auvik uses HTTP Basic auth with username:apiKey (not a bearer token), and the API base URL is region-pinned - your credentials only work against the cluster your tenant lives in.

Authentication

Auvik authenticates with HTTP Basic - the username is the Auvik user's email and the password is the API key.

| Field | Value | |-------|-------| | Auth scheme | HTTP Basic | | Username | AUVIK_USERNAME (your Auvik login email) | | Password | AUVIK_API_KEY |

The MCP server handles the basic-auth encoding. Set the env vars; do not pre-encode.

Region Routing

Auvik tenants live in one of several regional clusters:

| Region | Base host | |--------|-----------| | us1 | auvikapi.us1.my.auvik.com | | us2 | auvikapi.us2.my.auvik.com | | us3 | auvikapi.us3.my.auvik.com | | us4 | auvikapi.us4.my.auvik.com | | eu1 | auvikapi.eu1.my.auvik.com | | eu2 | auvikapi.eu2.my.auvik.com | | au1 | auvikapi.au1.my.auvik.com | | ca1 | auvikapi.ca1.my.auvik.com |

Set AUVIK_REGION to pin the region. If omitted, the server attempts to detect the region from the credentials. Misroutes typically surface as 404 or redirect loops on calls that should obviously succeed.

JSON:API Envelope

Auvik returns JSON:API-shaped responses. The tools surface this through to users, so know the shape:

{
  "data": [
    {
      "id": "...",
      "type": "device",
      "attributes": { ... },
      "relationships": { ... }
    }
  ],
  "links": { "next": "...", "prev": "...", "first": "...", "last": "..." },
  "meta": { "totalRecords": 1284, "totalPages": 26 },
  "included": [ ... ]
}

Key points:

• The record's real fields live under attributes, not the top level.
• Relationships to other entities are referenced under relationships, not embedded - use included (when present) for sideloads.
• Use links.next for the next page rather than constructing the URL yourself.

Singletons (*_get style tools) return data as an object, not an array.

Pagination

Auvik uses cursor-style pagination via links.next. Pattern:

1. Call the list tool. Read data and links.next.
2. If links.next is non-null, the tool exposes a way to fetch the next page (usually a page_first / page_after argument that the MCP server populates from the cursor).
3. Continue until links.next is null or your accumulated count reaches a sane cap.

Use page sizes of 100-500. Larger pages can time out on big tenants.

meta.totalRecords is the authoritative count - prefer it over counting accumulated rows when reporting size.

Rate Limits

Auvik enforces per-API-key rate limits. Behavior at limit:

• 429 status with a Retry-After header.
• The MCP server surfaces this as a tool error. Back off, then retry.
• If you're hitting limits routinely, narrow the query (one tenant at a time, smaller windows) rather than tightening the retry loop.

Statistics endpoints (auvik_statistics_*) are noticeably heavier than entity listings - rate-limit pressure usually shows up there first when scanning a large tenant.

v1 vs v2 Device API

Auvik exposes two generations of device endpoints. The MCP tools split them:

| Tool | API | |------|-----| | auvik_devices_list, auvik_devices_get | v1 - light record, fast | | auvik_devices_get_details | v2 - extended attributes | | auvik_devices_get_lifecycle | v2 - lifecycle fields | | auvik_devices_get_warranty | v2 - warranty fields |

Default to v1 for bulk listings; reach for v2 only when you need the extended fields. Calling v2 tools in a tight loop over a large device set is the single most common cause of rate-limit problems.

Multi-Tenant Routing

Auvik is multi-tenant by design - a single MSP credential sees every client tenant the MSP manages. Pattern:

1. auvik_tenants_list to enumerate visible tenants.
2. Filter and pass the chosen tenant_id (or tenantId, depending on the tool) on subsequent calls.
3. For fleet-wide reports, fan out across tenants client-side rather than expecting a single call to roll them up.

Error Handling

| Code | Meaning | Fix | |------|---------|-----| | 401 | Bad credentials | Check AUVIK_USERNAME + AUVIK_API_KEY | | 403 | Credentials valid, no access to the resource | Wrong tenant, or key lacks scope | | 404 | Unknown ID, or wrong region | Verify region; verify ID | | 429 | Rate limit | Back off; narrow the query | | 500 | Auvik-side hiccup | Retry, then escalate |

Best Practices

• Always pass tenant_id explicitly on per-tenant reports - implicit scoping is a source of cross-tenant data leaks in human-facing output.
• Default to v1 device endpoints; promote to v2 only for the device subset that needs it.
• For statistics queries, prefer short windows (24h) for interactive use and reserve longer windows (7d / 30d) for batch capacity reports.
• Cache auvik_tenants_list results within a session - the tenant list rarely changes.

Related Skills

• [devices](../devices/SKILL.md)
• [alerts](../alerts/SKILL.md)
• [networks](../networks/SKILL.md)