# Cisco Umbrella

> Cisco Umbrella is Cisco's cloud-delivered security service — DNS-layer security, secure web gateway, cloud-delivered firewall, CASB (Cisco Cloudlock) and remote browser isolation. The Umbrella API is a REST API at `https://api.umbrella.com`, authorized with OAuth 2.0 client credentials and split into six path scopes: `auth/v2`, `admin/v2`, `deployments/v2`, `investigate/v2`, `policies/v2` and `reports/v2`.

This file is generated by API Evangelist from Cisco's own published artifacts. It is a third-party profile, not a Cisco document.

## Getting started

- [Cloud Security API documentation](https://developer.cisco.com/docs/cloud-security/): Cisco DevNet home for the Umbrella and Cloudlock APIs.
- [Getting started](https://developer.cisco.com/docs/cloud-security/umbrella-api-getting-started/): create an API key and make a first call.
- [Authentication](https://developer.cisco.com/docs/cloud-security/umbrella-api-authentication/): OAuth 2.0 client credentials against `POST https://api.umbrella.com/auth/v2/token`; access tokens expire after one hour.
- [OAuth 2.0 scopes](https://developer.cisco.com/docs/cloud-security/umbrella-api-oauth-scopes/): 61 documented scopes across admin, deployments, investigate, policies and reports. Scopes are bound to the API key when it is created, not requested per token.
- [Pagination](https://developer.cisco.com/docs/cloud-security/umbrella-api-pagination/): `page`/`limit` for admin, deployments and policies; `limit`/`offset` for investigate and reports.
- [Rate limits](https://developer.cisco.com/docs/cloud-security/umbrella-api-rate-limits/): vary by scope, by resource and — for Investigate — by the organization's access tier. Exhaustion returns HTTP 429 with no rate-limit headers.
- [Errors and troubleshooting](https://developer.cisco.com/docs/cloud-security/umbrella-api-errors-troubleshooting/): errors are `{error, message, statusCode}` as `application/json`.
- [API changelog](https://developer.cisco.com/docs/cloud-security/umbrella-api-changelog/): dated entries, 46 of them, back to May 2020.
- [Sample scripts](https://developer.cisco.com/docs/cloud-security/umbrella-api-sample-scripts-overview/): Python samples plus the copy-and-paste Umbrella API client.

## Specifications

Cisco publishes 26 first-party OpenAPI 3.0 documents covering 256 operations. Each is downloadable from its reference page and from Cisco's docs CDN.

- [Cisco Umbrella Key Admin API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/key-admin.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-admin-overview/
- [Cicso Umbrella Managed Providers API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/managed-providers.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-managed-providers-overview/
- [Cisco Umbrella Providers API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/providers.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-providers-overview/
- [Cisco Umbrella S3 Bucket Key Rotation API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/s3-key-rotation.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-s3-key-rotation-overview/
- [Cisco Umbrella Service Providers Console API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/service-providers-console.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-managed-providers-overview/
- [Cisco Umbrella Users and Roles API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/admin/users-roles.yaml): base `https://api.umbrella.com/admin/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-users-roles-overview/
- [Cisco Umbrella Token Authorization API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/auth/token.yaml): base `https://api.umbrella.com/auth/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-authentication/
- [Cisco Cloudlock API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/cloudlock/cloudlock.yaml): base `https://api.cloudlock.com/api/v2` — documented at https://developer.cisco.com/docs/cloud-security/cloudlock-api-getting-started/
- [Cisco Umbrella Internal Domains API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/internal-domains.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-internal-domains-overview/
- [Cisco Umbrella Internal Networks API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/internal-networks.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-internal-networks-overview/
- [Cisco Umbrella Network Devices API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/network-devices.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-network-devices-overview/
- [Cisco Umbrella Network Tunnels API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/network-tunnels.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-network-tunnels-overview/
- [Cisco Umbrella Networks API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/networks.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-networks-overview/
- [Cisco Umbrella Deployments Policies API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/policies.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-deployment-policies-overview/
- [Cisco Umbrella Roaming Computers API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/roaming-computers.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-roaming-computers-overview/
- [Cisco Umbrella Sites API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/sites.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-sites-overview/
- [Cisco Umbrella Secure Web Gateway Device Settings API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/swg-devices.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-swg-devices-overview/
- [Cisco Umbrella Tagging API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/tagging.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-tagging-overview/
- [Cisco Umbrella Virtual Appliances API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/deployments/virtual-appliances.yaml): base `https://api.umbrella.com/deployments/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-virtual-appliances-overview/
- [Cisco Umbrella Investigate API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/investigate/investigate.yaml): base `https://api.umbrella.com/investigate/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-investigate-overview/
- [Cisco Umbrella Application Lists API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/application-lists-internet-umb.yaml): base `https://api.umbrella.com/policies/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-application-lists-overview/
- [Cisco Umbrella Destination Lists API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/policies/destination-lists.yaml): base `https://api.umbrella.com/policies/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-destination-lists-overview/
- [Cisco Umbrella API Usage Reports](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/api-usage.yaml): base `https://api.umbrella.com/reports/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-api-usage-overview/
- [Cisco Umbrella App Discovery API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/app-discovery.yaml): base `https://api.umbrella.com/reports/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-app-discovery-overview/
- [Providers Console Report](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/provider-consoles.yaml): base `https://api.umbrella.com/reports/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-reports-overview/
- [Cisco Umbrella Reporting API](https://pubhub.devnetcloud.com/media/cloud-security-apis-in-eft/docs/reference/reports/reporting.yaml): base `https://api.umbrella.com/reports/v2` — documented at https://developer.cisco.com/docs/cloud-security/umbrella-api-reference-reporting-overview/

## Runtime semantics

- Base URL: `https://api.umbrella.com/{scope}/v2` (Cloudlock CASB is separate: `https://api.cloudlock.com/api/v2`).
- Auth: `Authorization: Bearer <access_token>`; get the token with HTTP Basic against `POST https://api.umbrella.com/auth/v2/token`.
- Idempotency: not published. Cisco documents no idempotency key or header, so no write operation is documented as replay-safe.
- Rate limiting: HTTP 429 on exhaustion. No `RateLimit-*`, `X-RateLimit-*` or `Retry-After` header is published. Wait one second and retry.
- Errors: `{"error": "...", "message": "...", "statusCode": 400}` — a vendor envelope, not RFC 9457 problem+json.
- Versioning: in the path (`/v2`). Superseded v1 APIs live under https://developer.cisco.com/docs/legacy-umbrella-api/.
- Status: https://status.umbrella.com/ (Atlassian Statuspage; `api/v2/summary.json` is machine-readable).

## What Cisco does not publish for Umbrella

- No MCP server. The `CiscoDevNet/secure-access-mcp-community` server targets `api.sse.cisco.com` (Cisco Secure Access), not `api.umbrella.com`.
- No A2A agent card at `/.well-known/agent-card.json` or `/.well-known/agent.json` (real 404s on every host).
- No `/.well-known/` surface on `api.umbrella.com` at all — no api-catalog, no OIDC or OAuth server metadata, no llms.txt.
- No webhooks, events, streaming or AsyncAPI surface.
- No installable SDK in any package registry. The "Umbrella API Client" is a source listing inside the docs.
- No published prices: every package is quote-only.

## Optional

- [Umbrella product documentation](https://docs.umbrella.com/)
- [Cloudlock documentation](https://docs.umbrella.com/cloudlock-documentation)
- [Postman examples](https://github.com/CiscoDevNet/cloud-security/tree/master/Umbrella/PostmanExamples)
- [Cisco PSIRT security.txt](https://www.cisco.com/.well-known/security.txt)
- [Cisco Trust Portal](https://trustportal.cisco.com/c/r/ctp/trust-portal.html)
- [Umbrella SIG DevNet sandbox](https://devnetsandbox.cisco.com/RM/Topology?c=a6f8430c-5b24-439d-b28a-effb42d4c20c)