IP Ranges

1What it is

Every serious Genesys Cloud integration eventually lands on a network engineer's desk: the SMTP relay must accept Genesys' senders, the on-prem API behind Data Actions must open its firewall, the AudioHook receiver, the BYO bot/TTS/STT connectors, the SMPP gateway and the local key manager for recording encryption all need ingress or egress rules for address space Genesys owns. Genesys publishes that address space as an API — GET /api/v2/ipranges — one call that returns the complete public CIDR catalogue for every region, each entry tagged with its own region, the service that uses it, and the traffic direction. IP Ranges signs in once, pulls that catalogue, and turns it into a change-ticket-ready table.

• Filter to what the ticket needs — purpose chips (one per Genesys service, with live row counts), a region dropdown, an inbound/outbound/both control and free-text search, all stackable.
• Sort on any column — CIDR sorts numerically (by parsed address then prefix, IPv6 after IPv4), so the export reads like a routing table, not an alphabetised accident.
• Quantify the blast radius — a derived Addresses column (2^32−prefix per IPv4 block) and stat tiles totalling ranges, purposes, IPv4 addresses and regions in view.
• Export the evidence — CSV for tooling, a themed .xlsx for the change record, copy-as-JSON for automation. Exports contain exactly the current filtered + sorted view.

Who uses it

• Network / firewall engineers — building and reviewing allow-lists for Genesys Cloud integrations before raising the change request.
• Telephony / CX engineers — confirming which address space a given Genesys feature originates from (or connects to), per region, when a customer's security team asks.

2Quick start

1. Create (or reuse) an OAuth client — Genesys Cloud Menu > IT and Integrations > OAuth → Add client, grant type Client Credentials. The IP-range endpoint requires a valid token but no particular permission, scope or role — any client-credentials client in the org works.
2. Sign in — open the app, pick the region your org lives in (authentication only — you will see every region's data), paste the Client ID and Client Secret, press Connect. The full catalogue loads immediately.
3. Narrow to the change at hand — pick the deployment region in the top-bar Region dropdown, click the purpose chips for the services in scope (e.g. SMTP + IMAP for mail flows, Data Actions for mid-call callouts), and set direction if only one side of the flow matters.
4. Sort and export — click the CIDR header for numeric order, then CSV, Excel or Copy JSON. The file names carry the region filter (genesys-ipranges-<region|all-regions>.csv/.xlsx).
5. Before acting on it — press Refresh and check the footnote's fetch timestamp, so the ticket quotes today's catalogue, not last month's.

3UI walkthrough

Connect view

• AWS region dropdown — all 14 public Genesys Cloud regions (Mumbai, Seoul, Sydney, Tokyo, Canada, Frankfurt, Ireland, London, Zurich, UAE, São Paulo, US-East Virginia, US-East-2 FedRAMP, US-West Oregon), each shown with its API domain. Pick where your org authenticates.
• Client ID / Client Secret — the client-credentials pair. A failed connect shows an inline error banner carrying Genesys' own error description where available.
• Convenience memory — after a successful connect the client ID and region are kept in your browser and pre-filled next visit. The secret is never stored in the browser.
• A 📖 Read the user guide link opens this manual; it is also available signed-in via the top-bar 📖 Guide button.

Stats tiles & filters

Four stat tiles sit above the table and track the current filters live:

• IP ranges — rows in view, with the IPv4 / IPv6 split when both are present.
• Purposes — distinct services in view, plus which payload field they came from (field: service); says “not reported” if the payload carries no such field.
• IPv4 addresses — the sum of per-block host counts (2^32−prefix).
• Regions — regions in view, subtitled with the active region filter or “all in view”.

The filters themselves, all combinable:

• Region dropdown (top bar) — built from the distinct region values actually present in the payload, displayed with their friendly names (eu-west-2 · 🇬🇧 EU (London)). Purely a client-side filter over the loaded data — switching regions never re-authenticates or re-fetches. “All regions” resets it.
• Purpose chips — one colour-coded chip per service with its row count; the busiest purposes get the lead palette colours. Chips multi-select (click to toggle); “All purposes” clears the selection. Known service codes get friendly labels (see §4); unknown values are humanised automatically.
• Direction segmented control — All / Inbound / Outbound / Both; only rendered when the payload reports at least two distinct direction values.
• Free-text search — case-insensitive substring match across every field of the raw row (CIDR, purpose, region, and any extra columns Genesys adds).

The table & sorting

• Columns are discovered from the payload, not hard-coded: CIDR Block first (with the derived Addresses count beside it), then Purpose, Direction, Region, then any extra fields Genesys ships, humanised. Upstream schema additions appear automatically as new columns.
• Click a header to sort; click again to reverse. CIDR sorts numerically (parsed 32-bit base, then prefix; IPv6 blocks sort lexically and after IPv4); Addresses sorts numerically; text columns use a numeric-aware, case-insensitive compare.
• Row decorations — IPv6 rows carry a violet IPv6 badge; purpose cells show their palette dot; direction renders as a tinted badge (inbound sky, outbound amber, both violet). The Addresses cell is left blank (—) for IPv6 blocks, whose counts are astronomically large by design.
• “Showing X of Y” above the table reports the filter's effect; the footnote below it shows the exact upstream source URL and the fetch timestamp.

Exports & actions

All three exports operate on the current filtered + sorted view — what you see is exactly what you ship in the ticket.

• CSV — the discovered data columns in table order plus a trailing addressCount column (blank for IPv6); values quoted per RFC where needed.
• Excel — a real themed .xlsx workbook (sheet “Genesys IP Ranges”): royal-blue #0F62FE header row in bold white Arial 10, light zebra body, thin rules, right-aligned #,##0 counts, purpose text tinted in the app's palette, frozen header and an auto-filter — assembled entirely in the browser (see §6).
• Copy JSON — copies {"addresses":[…]} to the clipboard, the raw Genesys rows of the current view verbatim, ready to paste into automation.
• Refresh — re-fetches from Genesys (with a silent token refresh if the session's bearer token has expired). Sign out ends the session and returns to the connect form.

4Data semantics

What the Genesys endpoint returns

GET /api/v2/ipranges takes no parameters and returns an IpAddressRangeListing — { entities: IpAddressRange[] } — covering the public address space for every Genesys region at once; each entry carries its own region tag:

The purposes (service enum)

The app maps the raw service codes to friendly labels; values Genesys adds later are humanised automatically and appear as new chips:

Derived and defensive behaviour

• Addresses column — computed client-side as 2^32−prefix for IPv4 blocks (the full block size, network and broadcast included); intentionally blank for IPv6.
• Schema tolerance — the app never hard-codes the payload shape. It finds the row array (entities first, then addresses, then the first array in the object) and detects the CIDR / purpose / direction / region columns by candidate-name lists (cidr|address|ipAddress|…, service|purpose|type|…), so upstream renames degrade gracefully and additions surface automatically.
• Snapshot semantics — the table shows the payload from the moment of the last fetch; the footnote records the source URL and timestamp, and Refresh re-queries live.

5Genesys endpoints & permissions

The app talks to exactly two Genesys endpoints — nothing else:

Authentication is required but unprivileged. The endpoint is not public — it returns 401 without a bearer token — but it demands no specific permission, role or scope: any client-credentials OAuth client that can authenticate against the org can read it (verified). That makes the sign-in a formality of having an org, not of having rights in it.

• Login region matters, data region doesn't — an OAuth client can only authenticate against its own org's login.<domain>; the response then spans all regions regardless.
• There is deliberately no “switch region” re-authentication — the region control is purely a filter over data already loaded.

6Technology

• Web application — a small service with no database: credentials and the Genesys token are held on the server and never sent to the browser, and an expired Genesys token is renewed transparently and the call retried.
• Browser interface — columns, purpose chips and the direction control are discovered from the Genesys payload at runtime, so upstream schema changes surface automatically.
• Excel export — the .xlsx workbook is assembled entirely in your browser; the file contains exactly the current filtered + sorted view, styled to match the app.

7Troubleshooting

“Authentication failed (HTTP 4xx)” on Connect.

Wrong client ID/secret — or valid credentials for an org in a different region than the one selected: a client can only authenticate against its own org's login.<domain>. The banner shows Genesys' own error description when it sends one.

“The service is busy. Try again later.”

The service is handling as many sign-ins as it can. Try again shortly — reconnecting with the same client and region reuses your existing session.

I keep landing back on the Connect screen.

Your session ended after a period of inactivity. Sign in again; the last client ID and region are pre-filled from the browser, and nothing else was kept.

“Failed to load IP ranges — …” banner after connecting.

The upstream GET /api/v2/ipranges call failed. The app already retried once with a fresh token (the expired-token case); other errors are shown as reported. The table area shows an empty state until a successful Refresh — check Genesys status and retry.

The Purposes tile says “not reported” and there are no chips.

The payload carried no purpose/service field (columns are discovered dynamically). Everything else still works — filter with the search box instead.

The Direction control is missing.

It only renders when the payload reports at least two distinct direction values. Nothing is wrong — the current catalogue simply doesn't distinguish directions.

Why is the Addresses cell empty on some rows?

Those are IPv6 blocks — counts are omitted as meaninglessly large. The column shows the IPv4 block size, 2^32−prefix.

Does switching region re-query Genesys?

No. One call returned every region's ranges; the Region dropdown filters rows client-side. Use Refresh to re-query live.

Is anything stored on the server?

Only your session (client ID, secret, token) while you are signed in — nothing is written to storage. The browser remembers the last client ID and region as a convenience; the secret never leaves the server.