Connect Cisco Umbrella

Cisco Umbrella is a cloud-delivered security platform: DNS-layer security, a secure web gateway, a cloud-delivered firewall, and — as a separately-licensed add-on — the Investigate threat-intelligence dataset. MSPs use it to enforce web and DNS policy, inspect traffic, and hunt threats across their client organizations.

Connecting Umbrella to StackJack gives your AI assistant a broad family of umb_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Deploy and manage networks, IPsec tunnels, sites, virtual appliances, roaming computers, network devices, internal networks, and internal domains
• Control policy — read and edit destination (allow/block) lists and application lists, and attach or detach identities on deployment policies
• Report on DNS, proxy, and firewall activity — top destinations, identities, and threats, request/category/bandwidth aggregations and summaries, App Discovery (shadow IT), and your own API-key usage
• Administer the org — users, roles, and API keys
• Manage provider consoles — the Managed Providers (Multi-Org/MSP) console and the Service-Provider/MSSP console: partner customer CRUD, packages and subscriptions, trial lifecycle, delegated access-requests, console branding, and provider-wide reporting
• Investigate (Pro, license-gated) domains, IPs, and files against Cisco's threat-intelligence graph: WHOIS (history, by-nameserver, by-email, search), passive DNS, BGP routes, subdomains, co-occurrences, risk scores, and sample analysis
• Act (on Pro plans) — create, update, and delete the deployment, policy, admin, and provider-console objects above

How StackJack authenticates to Cisco Umbrella

Umbrella issues API credentials as a pair, created together in the Umbrella dashboard: an API Key (the public identifier) and an API Key Secret (the private secret). StackJack Basic-authenticates that pair to mint a short-lived bearer token from POST https://api.umbrella.com/auth/v2/token, then caches it and re-mints it automatically before it expires — nothing for you to manage. There is no refresh token — recovery is always a fresh token request, so a revoked key fails closed on the next mint.

The base URL is fixed at https://api.umbrella.com for commercial orgs. (Umbrella for Government customers are on a separate host.) StackJack stores that default for you, so you normally leave the URL field blank.

One configured key pair mints one parent/provider access token in StackJack. Cisco also supports minting a child-organization token from provider credentials by sending X-Umbrella-OrgId during token creation, but StackJack does not currently collect or send that child ID. Operational tools therefore act in the configured credential's own parent/provider organization. Provider endpoints whose tools take a customerId still work with a provider-tier key carrying the required admin/config/reporting scopes. Configure a separate credential context if you need direct operational access as a child organization.

Before you begin

• In StackJack: you need a role that can manage connectors — tenant Owner, a co-owner, or an Administrator.
• In Umbrella: you need the Full Admin role to create an API key.
• Decide which scopes you need. The scopes you grant the key gate what StackJack can do — see "Scopes drive tool access" below. Grant at least Deployments (read) even if you do not use Deployment tools, so save-time validation and later Re-test can validate.
• Review Cisco's current Umbrella API authentication, getting-started, pagination, and rate-limit guidance.

Step 1 — Generate API credentials in Cisco Umbrella

1. Sign in with the Full Admin role. Go to Admin → API Keys; in a Multi-org, MSP, or MSSP console, use Console Settings → API Keys.
2. Select API Keys → Add and give the key a recognizable name and description.
3. Choose the required resource scopes and Read-Only or Read / Write access. Add Investigate only if you hold that license.
4. Choose an Expiry Date (or Never expire). Optionally add Network Restrictions for the public IP addresses or CIDRs allowed to use the key; Cisco permits up to ten entries. If you restrict the key, open a support ticket first to get StackJack's current outbound addresses for your region: they are not published, and a region move changes them.
5. Create the key and copy the API Key and API Key Secret immediately. Cisco does not show the secret again.

Scopes drive tool access

A key's scopes decide which tools work. A key granted Read-Only on a family can run that family's read tools (the Free-tier surface) but cannot call its Pro write tools — a write attempt returns 403. If a Pro write tool 403s, re-issue the API key with the family's write scope (for example edit:admin for user and API-key writes); it is not a "connector not configured" error.

Include the Deployments (read) scope even if you do not use Deployments tools. Save-time validation and Re-test call a Deployments endpoint, so a key scoped only to another family can show Needs Attention while its in-scope tools still work. Adding Deployments read produces a clean whole-connector validation result.

Investigate requires a separate license

The umb_investigate_* threat-intelligence family queries Cisco's Investigate graph, which is a separately-purchased Umbrella Investigate add-on (a paid, tiered subscription). Without it — and without the Investigate scope on your key — those tools return 403/404. umb_investigate_samples additionally requires a Cisco Secure Malware Analytics license. Every other tool works with a standard Umbrella subscription. Investigate tools are read-only but ship on the Pro tier.

Step 2 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Select the Cisco Umbrella tile to open its details. Choose How To Connect to review the inline setup guide, or Configure to reveal the credential form in the drawer.
3. Paste the API Key into the API Key field and the API Key Secret into the API Key Secret field. Leave the URL blank to use the commercial cloud (https://api.umbrella.com); set it only for Umbrella for Government.
4. Click Save.

What happens when you save

• The key and secret are stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure Umbrella, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack immediately live-validates the credentials by minting a token and calling a Deployments read. Validation never blocks the save.
• After saving, the form collapses and the connector drawer stays open. It shows Connected / Valid on success, or Needs Attention with Re-test and recovery guidance if validation failed.

Plans and available tools

• Free includes Deployments, Policies, Reports, and Admin reads — networks, tunnels, sites, devices, destination lists, application lists, deployment policies, activity/aggregation/summary reports, App Discovery, API usage, users, roles, API-key metadata, and the Managed-Provider / Service-Provider console reads (customers, packages, subscriptions, branding, provider reporting).
• Pro adds write and action tools (creates, updates, deletes, tag/identity/destination changes, provider-console management, and key/credential rotations) plus the read-only Investigate intelligence family.
• Business offers the same tool set as Pro with a higher monthly call quota — it unlocks no additional tools.

See the generated Cisco Umbrella tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.

Umbrella has no per-user OAuth (PKCE) sign-in, so there is no per-user attribution — all AI traffic uses the shared key pair on every tier. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Safety note: several Pro tools delete or detach state and are irreversible — for example umb_delete_destination_list, umb_delete_roaming_computer, umb_delete_user, and umb_remove_destinations. Scope your AI's access deliberately: use the tool selections on the MCP Setup page and the Permissions page to enable only the actions you want an AI to take, and consider a read-only-scoped key unless you specifically need write tools.

Rate limits

Umbrella publishes different limits by scope and resource. General Admin, Deployments, and provider-console operations can be limited to 14 requests per minute per key, while Policies permits much more; Investigate also varies by license tier and endpoint. StackJack applies a 60-call-per-minute tenant pace and records upstream 429 backoff, but one generic limiter cannot model every family. Narrow large requests and honor the upstream retry delay when a lower family-specific quota is reached.

Pagination

Collection endpoints generally use one-based page plus limit; the default is up to 200 records. Maximums vary — for example, networks allow 1,000 while roaming computers and destination-list entries allow 100, and some endpoints are not paginated. Use each tool's schema and returned page metadata rather than assuming a universal page size.

Rotating or replacing the credentials

Umbrella reveals the API Key Secret only at creation, so if you lose it you must rotate rather than look it up. The lowest-risk approach is:

1. Create a new key with the required scopes, expiry, and network restrictions, and copy its secret once.
2. Update Connectors → Cisco Umbrella → Configure, save, and confirm Valid.
3. Delete the old key only after the replacement works. If you instead use Umbrella's Refresh Key action, the old pair stops working immediately, so update StackJack without delay.

Disconnecting Cisco Umbrella

StackJack's Disconnect action deletes its stored key pair and stops future calls. It does not delete or revoke the key in Umbrella. Remove that key separately under Admin → API Keys or Console Settings → API Keys if no other integration uses it. Subscription changes are separate from credential removal.

Several customers

Some MSPs need one Cisco Umbrella connection per customer, console or region. StackJack can hold several named connections of one connector, and your AI names the one it wants on each call. See Several connections of one connector.

Troubleshooting

Cisco Umbrella tools

umb_ · 233 tools · Free 140 · Pro 93

Admin

API Keys

Networks

Sites

Tunnels

Internal Domains

Devices & Tags

Destination Lists

Deployment Policies

Reports

App Discovery

API Usage

Investigate

Managed Providers

Provider Customers

Provider Trials & Access

Provider Deals & Organizations

Provider Branding

Provider Reporting

Report Aggregations

Report Summaries

Application Lists

SWG Device Settings