Cisco Umbrella User Management API Guide

Auth method: HTTP Basic Auth using API key (key ID as username, key secret as password); OAuth 2.0 client credentials flow used for some newer Umbrella platform APIs

Setup steps

1. Log in to the Cisco Umbrella dashboard as an admin.
2. Navigate to Admin > API Keys.
3. Create a new API key, selecting the appropriate key type (Management API or Reporting API).
4. Copy the Key ID and Key Secret - the secret is shown only once.
5. Use the Key ID as the HTTP Basic Auth username and Key Secret as the password in API requests.
6. For OAuth 2.0 flows (newer platform APIs), POST to the token endpoint with client_id and client_secret to obtain a bearer token.

Required scopes

List Users

• Method: GET
• URL: https://management.api.umbrella.com/v1/organizations/{organizationId}/users
• Watch out for: organizationId is required in the path; retrieve it from the dashboard or the /organizations endpoint.

Request example

GET /v1/organizations/12345/users?page=1&limit=100
Authorization: Basic {base64(keyId:keySecret)}

Response example

[
  {
    "id": 67890,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "role": "Admin"
  }
]

Get User

• Method: GET
• URL: https://management.api.umbrella.com/v1/organizations/{organizationId}/users/{userId}
• Watch out for: Returns 404 if userId does not exist in the specified organization.

Request example

GET /v1/organizations/12345/users/67890
Authorization: Basic {base64(keyId:keySecret)}

Response example

{
  "id": 67890,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "Admin",
  "status": "active"
}

Create User

• Method: POST
• URL: https://management.api.umbrella.com/v1/organizations/{organizationId}/users
• Watch out for: Email must be unique; duplicate email returns 400. Role values are case-sensitive.

Request example

POST /v1/organizations/12345/users
Content-Type: application/json

{"name":"John Smith","email":"john@example.com","role":"Admin"}

Response example

{
  "id": 67891,
  "name": "John Smith",
  "email": "john@example.com",
  "role": "Admin"
}

Update User

• Method: PUT
• URL: https://management.api.umbrella.com/v1/organizations/{organizationId}/users/{userId}
• Watch out for: PUT replaces the full user object; omitting optional fields may reset them.

Request example

PUT /v1/organizations/12345/users/67891
Content-Type: application/json

{"name":"John Smith","role":"Read-Only"}

Response example

{
  "id": 67891,
  "name": "John Smith",
  "email": "john@example.com",
  "role": "Read-Only"
}

Delete User

• Method: DELETE
• URL: https://management.api.umbrella.com/v1/organizations/{organizationId}/users/{userId}
• Watch out for: Deleting the only admin user may be blocked. Action is irreversible.

Request example

DELETE /v1/organizations/12345/users/67891
Authorization: Basic {base64(keyId:keySecret)}

Response example

HTTP 204 No Content

List Organizations

• Method: GET
• URL: https://management.api.umbrella.com/v1/organizations
• Watch out for: MSP/partner keys may return multiple organizations; single-org keys return only one.

Request example

GET /v1/organizations
Authorization: Basic {base64(keyId:keySecret)}

Response example

[
  {
    "organizationId": 12345,
    "name": "Acme Corp"
  }
]

• Rate limits: Cisco Umbrella enforces rate limits on Management API calls. Official documentation does not publish exact per-plan numeric limits publicly.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when limits are exceeded. Retry-After header may be present. Cisco recommends exponential backoff. Exact limits are not published in official docs.
• Pagination method: offset
• Default page size: 100
• Max page size: 200
• Pagination pointer: page and limit (e.g., ?page=1&limit=100)

• Webhooks available: No
• Webhook notes: Cisco Umbrella does not offer native outbound webhooks for user or policy change events as of the current documentation.
• Alternative event strategy: Use the Reporting API or Cisco SecureX/XDR integrations to poll for events and audit logs.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://management.api.umbrella.com/scim/v2

• Supported operations: GET /Users, GET /Users/{id}, POST /Users, PUT /Users/{id}, PATCH /Users/{id}, DELETE /Users/{id}, GET /Groups, POST /Groups, PUT /Groups/{id}, DELETE /Groups/{id}

Limitations:

• Requires Enterprise plan.
• SSO (SAML) must be configured before enabling SCIM provisioning.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and OneLogin.
• SCIM token is generated in the Umbrella dashboard under Admin > Authentication > SCIM.
• SCIM token does not expire by default but must be regenerated if rotated.
• Group push maps to Umbrella user groups; not all IdP group attributes are supported.
• Deprovisioning via SCIM deactivates users but may not immediately revoke active sessions.

Three primary automation scenarios are supported by the API.

First, admin user provisioning: obtain organizationId from GET /v1/organizations, then POST /v1/organizations/{organizationId}/users with name, email, and role - note that role values are case-sensitive and the invited user must still accept an email invitation before the account is active.

Second, full lifecycle automation via SCIM with Okta, Entra ID, or OneLogin: generate a SCIM token in Admin > Authentication > SCIM, configure the Umbrella app in your IdP using the SCIM base URL and token, then enable create, update, and deactivate operations - if the token is regenerated in Umbrella, it must be re-entered in the IdP immediately or provisioning breaks.

Third, bulk user reads for audit or reconciliation: paginate GET /v1/organizations/{organizationId}/users using ? page=1&limit=200 (max page size), incrementing until the response count falls below the limit - do not rely on a total field in the response.

Provision a new admin user via Management API

1. Obtain the organizationId from GET /v1/organizations using your Management API key.
2. POST to /v1/organizations/{organizationId}/users with name, email, and role fields.
3. Verify creation by calling GET /v1/organizations/{organizationId}/users/{newUserId}.
4. Notify the user - Umbrella sends an invitation email to the provided address.

Watch out for: The user must accept the email invitation before they can log in; the API does not bypass this flow.

Automate user lifecycle with SCIM via Okta

1. Confirm Umbrella Enterprise plan is active and SSO (SAML) is configured with Okta.
2. In Umbrella dashboard, navigate to Admin > Authentication > SCIM and generate a SCIM token.
3. In Okta, add the Cisco Umbrella app from the Okta Integration Network.
4. Configure SCIM provisioning in Okta using the Umbrella SCIM base URL and the generated token.
5. Enable Create Users, Update User Attributes, and Deactivate Users in Okta provisioning settings.
6. Assign users or groups in Okta to push them to Umbrella automatically.

Watch out for: SCIM token must be re-entered in Okta if regenerated in Umbrella; existing provisioning will break until updated.

Bulk-read all users for an organization

1. Call GET /v1/organizations/{organizationId}/users?page=1&limit=200.
2. Check if the response contains exactly 200 records; if so, increment page and repeat.
3. Continue paginating until a response returns fewer than the limit, indicating the last page.
4. Aggregate all results into a local dataset for auditing or reconciliation.

Watch out for: Max page size is 200; requesting more may return an error or be silently capped. Always check response count rather than relying on a total field.

Several API behaviors create silent failure risk. The Management API and Reporting API use separate key types scoped at creation time - a Reporting key cannot call Management endpoints and will return auth errors with no clear indication of scope mismatch.

The organizationId path parameter is required on nearly every endpoint; MSP or partner keys may return multiple organizations from GET /v1/organizations and must iterate per org. Rate limit thresholds are not publicly documented - implement exponential backoff on HTTP 429 responses and check for the Retry-After header.

On the SCIM side, DELETE /Users/{id} deactivates rather than hard-deletes in some configurations, while DELETE via the Management API is permanent and irreversible - verify which behavior applies in your environment before building deprovision logic. SCIM deactivation also may not immediately revoke active sessions, leaving a window where a deprovisioned user retains access.