Skip to main content

​
About Cisco IQ

Cisco IQ (iq.cisco.com) is Cisco’s AI-powered support and services platform. Its API exposes your account’s install base: assets with contract coverage and lifecycle milestones, support contracts, PSIRT security advisories, and field notices, together with which of your assets each advisory or notice affects. The API is read-only - every operation is a read, so nothing in Serval can change data in Cisco IQ. The integration is marked Beta in the connect screen, and Cisco’s own API is in beta (public preview): Cisco states that endpoint paths, schemas, and authentication may change between releases without backward compatibility. Authentication: A long-lived Cisco IQ token - a service account token (recommended) or personal access token - plus your account ID and data storage region. Serval stores the token encrypted and exchanges it server-side for a short-lived access token (about an hour) before calling the API, so workflows never handle either token. Data sync: No background sync starts when you connect. Data access is on-demand through workflows, plus one installable ingestion workflow, “Ingest Assets from Cisco IQ”, that syncs your Cisco install-base inventory into Serval as assets.

​
What the Cisco IQ integration enables

Typical workflow questions this answers: which assets are hit by a given PSIRT advisory, which contracts or coverage windows expire in the next quarter, and which hardware reaches end of support this year.

​
Get your credentials

Serval needs a Cisco IQ token, your account ID, and the account’s data storage region. Use a service account rather than a personal token: personal tokens act as a specific person and stop working when that person’s access changes.
1

Create a service account in Cisco IQ

Sign in to Cisco IQ as an Account Administrator and go to System Settings, then Identity and Access, then Add User. Choose the Service Account type. Service accounts are available on customer accounts only - partner accounts must use a personal access token instead (created under your name, then User Settings, then Generate Token).
2

Give it the access Serval should have

A Viewer role is sufficient - the integration only reads. Resource groups, if you use them, narrow which assets the account can see; what Serval can read is exactly what this account can read.
3

Create the token and copy it immediately

The token is shown once at creation and never again. A service account supports up to five concurrent tokens (manage them under Manage API Tokens on the service account), which is what makes zero-downtime rotation possible later.
4

Note your account ID and data storage region

Both are shown in Cisco IQ under System Settings, then Account Details. The region is US, EMEA, or APJC.

​
Connect in Serval

1

Open the Cisco IQ connect form

Add a new Cisco IQ connection (marked Beta) from your Serval integrations page.
2

Name the connection

The Instance Name field is “A name to identify this Cisco IQ connection, such as Production.”
3

Enter the Account ID and Data Storage Region

Both come from System Settings, then Account Details in Cisco IQ. The region is a dropdown with US, EMEA, and APJC - entering the wrong region routes requests to the wrong data residency zone, and the connection fails.
4

Paste the API Token

The API Token field takes “A Cisco IQ service account token (recommended) or personal access token.” All four fields are required - a missing one is rejected with a message such as “Account ID is required” or “API token is required”.
5

Submit the form, then run the health checks

The credentials are not tested at save time, so run the health checks right after connecting (see below).
To rotate the token later, create the replacement token in Cisco IQ first, edit the connection and paste only the new token (updating with the token field left blank keeps the stored one), confirm the health checks pass, and only then revoke the old token in Cisco IQ. Revoking first breaks the connection.

​
Verifying the connection

The connection ships four health checks that make live calls to Cisco IQ:
  • Validate API connection - exchanges the stored token for an access token and reads the asset inventory. On success: “Successfully connected to Cisco IQ. [number] assets are visible to this account.” On failure: “Unable to connect to Cisco IQ. Verify the API token, the account ID, and the data storage region.”
  • List contracts - reads a single support contract. On failure: “Unable to read contracts. Verify the account’s role and resource groups in Cisco IQ.”
  • List security advisories - reads a single security advisory. On failure: “Unable to read security advisories. Verify the account’s role and resource groups in Cisco IQ.”
  • List field notices - reads a single field notice. On failure: “Unable to read field notices. Verify the account’s role and resource groups in Cisco IQ.”
Each of the last three can also pass with a “Connected, but…” message when the account simply has none of that record type visible - that is a healthy connection with an empty collection, not a failure.

​
Gotchas and troubleshooting

Cisco publishes these APIs as beta (public preview) and states that paths, schemas, authentication, and pagination may change between releases without backward compatibility. Serval tracks the API as it evolves, but a Cisco-side change can break the integration until it is updated - which is why the connection is marked Beta.
Authentication and authorization are separate in Cisco IQ: a valid token whose account lacks access returns 403, not 401. What the account can see is set by its role (Administrator or Viewer), its resource groups, and Cisco’s own entitlement rules. Cisco also notes that permission changes take from a few minutes to almost an hour to propagate - a 403 right after a permissions change may resolve itself.
Cisco IQ enforces 10 requests per second and 5,000 per 24 hours per user or service account, and 25 per second and 25,000 per 24 hours per account - all users and integrations in the account share that account-wide budget. Serval’s ingestion uses the largest page size (200 assets per request) to stay well inside it, but heavy custom workflows plus other API consumers in the same account can exhaust the shared window, which returns HTTP 429 until it resets.
Assets become external assets keyed by their Cisco IQ asset ID (falling back to serial number), named after the asset’s hostname, falling back to its serial number. The full Cisco IQ asset record - contract coverage, lifecycle milestones, telemetry status, and the rest - is attached to each asset.
Cisco IQ list responses carry a total count that can be null, meaning unknown - not zero. The first health check reports the count only when Cisco IQ provides one, and paging in workflows should stop on a short page rather than on the count.
An access token is scoped to exactly one Cisco IQ account. To work across several accounts (or to scope different teams to different resource groups), create one Serval connection per account or per service account - the instance name keeps them distinct.
Need help? Contact support@serval.com for assistance with your Cisco IQ integration.