admin / Synapse-Cortex

# Quick Guide: NetscanXi → Synapse-Cortex v2 API Setup

Connect NetscanXi's asset discovery to Cortex's CMDB in under five minutes — the same setup also lets NetscanXi auto-create Cortex tickets from its Remediation Tracking items. NetscanXi pushes both to Cortex; Cortex never reaches out to NetscanXi.

**What's new in v2:** the integration itself — endpoints, request/response shapes, the API key model — is unchanged from v1. Cortex's whole tenant UI moved to a React single-page app in v2, but that's purely front-end; NetscanXi talks to the same `/api/ingest/assets` and `/api/ingest/tickets` endpoints exactly as before.

**You'll need:** a `tenant_admin` or `global_admin` account in Cortex, and a `tenant_admin`+ account in NetscanXi.

---

## Step 1 — Generate the API key in Cortex

1. Log in to Synapse-Cortex.
2. Go to **Admin → Integrations** in the left sidebar.
3. Click **Generate API Key**.
4. Copy both values shown — you need them in the next step.

Two values appear after step 4:

- **API URL** — the *base* address of your Cortex instance (e.g. `https://cortex.yourcompany.com`, **no path** after it). NetscanXi appends its own ingest path automatically; pasting a URL that already has a path on it will cause requests to 404.
- **API Key** (starts with `cortex_in_...`)

> The key is shown **once**. If you navigate away before copying it, click **Regenerate API Key** to get a new one — the old key stops working immediately.

## Step 2 — Enter the key in NetscanXi

1. Log in to NetscanXi.
2. Click **Synapse Cortex** in the toolbar.
3. Paste the **API URL** and **API Key** from Step 1 into the matching fields.
4. Check **Enable sending asset data to Synapse Cortex**.
5. Click **Save**.

## Step 3 — Test the connection

1. Still in the **Synapse Cortex** panel, click **Test Connection**.
2. You should see **OK Connected**.

If you see **Failed to Connect** instead:

| Symptom | Likely cause | Fix |
|---|---|---|
| `HTTP 404: {"detail":"Not Found"}` | API URL has a path on it (e.g. ends in `/api/ingest/assets`) | Re-copy the URL from Cortex Admin → Integrations — it should be just the base address, nothing after the host/port |
| Failed immediately | Wrong or revoked API key | Regenerate the key in Cortex and re-paste it |
| Timeout / unreachable | Network path blocked | Confirm NetscanXi's host can reach Cortex's host/port over HTTPS |

## Step 4 — Push your first scan

1. Run or select a completed scan in NetscanXi.
2. In the **Synapse Cortex** panel, click **Send latest scan now**.
3. Switch to Cortex and open **Assets (CMDB)** — the discovered devices should now appear, tagged **NetscanXi** in the Source column.

## Step 5 — Confirm the data landed correctly

Click into any imported asset in Cortex and check:

- **Asset ID** matches the ID shown for that device in NetscanXi.
- **Network** section shows the correct MAC/IP.
- **Discovered OS & Software** section shows the OS and software NetscanXi found.

That's it — future scans keep syncing the same way. Re-pushing a scan updates existing assets in place; it never creates duplicates.

## Step 6 — Also push tickets (optional)

The same key and connection also cover ticket auto-creation, no extra setup needed:

1. In NetscanXi's **Synapse Cortex** panel, scroll to **Auto-create tickets in Synapse Cortex**.
2. Click **Send remediation items as tickets**.
3. In Cortex, open **Tickets** — items from NetscanXi's Remediation Tracking module now appear as tickets, tagged **NetscanXi** in the Source column, linked to their asset when one was already imported.

Unlike assets, ticket push is **create-only**: a ticket is created once per remediation item and left alone on every later push, so nothing an agent does to it in Cortex afterward gets overwritten. See the [Administrator Guide](admin-guide.md) for the full status/priority mapping.

A ticket auto-created this way, with a linked asset carrying a known OS, is a natural fit for the new **AI Remediation Module** covered in the Administrator Guide (Section 9) and User Guide (Section 6) — the integration itself doesn't need any extra setup for that; it's a separate, independently-enabled module.

---

## Turning it off

- **Pause temporarily**: uncheck **Enable** in NetscanXi's Synapse Cortex panel. The key stays valid for later.
- **Revoke permanently**: in Cortex, go to **Admin → Integrations** and click **Revoke**. NetscanXi's next push attempt will fail with an authentication error until a new key is generated and re-entered.

For full details on what fields are imported and how asset IDs are reconciled between the two systems, see the [Administrator Guide](admin-guide.md).