> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cisco IQ

> Connect Serval to Cisco IQ so workflows can read your Cisco install base - assets, contracts, lifecycle milestones, security advisories, and field notices - and sync the asset inventory into Serval.

## 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

| Capability               | Description                                                                                                                                                                                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cisco IQ API access      | Workflows use the "Cisco IQ API request" action to call the Cisco IQ product API - assets (with 51 filter parameters), asset lifecycle milestones, asset relationships, contracts, security advisories, field notices, and the affected-asset views that connect advisories and notices to your inventory. |
| Asset ingestion          | The installable "Ingest Assets from Cisco IQ" workflow syncs the install-base inventory - hostname, serial number, product, software version, contract coverage, lifecycle milestones, and telemetry status - into Serval as external assets.                                                              |
| Connection health checks | Four built-in checks confirm the token works and that the account can read assets, contracts, security advisories, and field notices.                                                                                                                                                                      |

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.

<Steps>
  <Step title="Create a service account in Cisco IQ">
    Sign in to [Cisco IQ](https://iq.cisco.com) 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**).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the Cisco IQ connect form">
    Add a new Cisco IQ connection (marked Beta) from your Serval integrations page.
  </Step>

  <Step title="Name the connection">
    The **Instance Name** field is "A name to identify this Cisco IQ connection, such as Production."
  </Step>

  <Step title="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.
  </Step>

  <Step title="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".
  </Step>

  <Step title="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).
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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

<AccordionGroup>
  <Accordion title="The Cisco IQ API is beta">
    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.
  </Accordion>

  <Accordion title="Health checks fail with authorization errors after the token is confirmed valid">
    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.
  </Accordion>

  <Accordion title="Rate limits are shared and modest">
    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.
  </Accordion>

  <Accordion title="How synced assets are identified and named">
    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.
  </Accordion>

  <Accordion title="Totals can be unknown">
    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.
  </Accordion>

  <Accordion title="One connection sees one account">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Cisco IQ integration.