Get Entitlements

Entitlements (v0.2.0)

Overview

The Manage Entitlement API provides comprehensive capabilities for managing entitlements within the RUCKUS One platform. Entitlements represent the authorization and rights to use RUCKUS products and services, encompassing licenses, subscriptions. This API enables you to manage these entitlements, track their usage, control assignments to partners and customers, and monitor compliance.

The API is designed for organizations that need to manage entitlements including licenses and subscriptions, track device usage, allocate entitlements to customers or partners, and maintain compliance with subscription agreements.

What This API Does

Entitlement Management: Retrieve and query detailed entitlement information including purchased licenses, assigned licenses, entitlement types
Usage and Utilization: Access real-time usage statistics, track license usage
Entitlement Availability: Calculate available entitlement capacity, determine allocation availability based on current usage, and access banner notifications for entitlements requiring attention
Assignment Management: Create, retrieve, update, and delete entitlement assignments
Synchronization: Synchronize entitlement data from latest purchase
Query Operations: Retrieve entitlement and assignment data with pagination, sorting, and filtering capabilities
Compliance Monitoring: Monitor entitlement compliance status and identify licenses that exceed allocations or are underutilized

Common Use Cases

Enterprise Entitlement Management: Track and manage entitlements across large organizations with multiple departments or business units
MSP/VAR Operations: Allocate and manage entitlements for customer accounts.
Usage Reporting: Generate periodic usage reports for capacity planning.
Compliance Auditing: Monitor entitlement usage to ensure compliance with subscription terms and conditions

Technical Details

API Version: v0.2.0
Content Types: Supports application/json and application/vnd.ruckus.v1+json for v1 endpoints
Regional Endpoints: Available in North America, Europe, and Asia Pacific regions

Authentication & Authorization

This API uses bearer token authentication with role based access control. Users must have appropriate permissions to perform operations on entitlements, assignments, and usage data.

Download OpenAPI description

Download PDF

Overview

URL

http://support.ruckuswireless.com

Support Team

support@ruckuswireless.com

License

RUCKUS Cloud Privacy Policy

Servers

RUCKUS One API host for North American region.

https://api.ruckus.cloud

RUCKUS One API host for European region.

https://api.eu.ruckus.cloud

RUCKUS One API host for Asian region.

https://api.asia.ruckus.cloud

Entitlement

Entitlement management and license operations.

Operations

Get EntitlementsDeprecated

Request

Retrieves the list of device entitlements for the authenticated tenant. This method will be removed no sooner than 08/31/2026. The following '/entitlements/query' can be used for this content.

Query

typestring

Filter by device type (optional). If device agnostic sku feature is enabled, all device types will be treated as APSW except ANALYTICS.

Enum"IOT_CTRL""UNASSIGNED_DEVICE_TYPE""WIFI""LTE""SWITCH""ANALYTICS""RWG""EDGE""VIRTUAL_EDGE""APSW"

licenseTypestring

Filter by license type (optional)

Enum"UNKNOWN""APSW""URLF""EDGE_SECS""EDGE_SECL""SLTN_TOKEN"

No request payload

Responses

Returns the entitlements.

Bodyapplication/jsonArray [

idstring

createdDatestring(date-time)

Timestamp when the entitlement record was created in the system.

updatedDatestring(date-time)

Timestamp when the entitlement record was last updated in the system.

externalIdstring

External identifier for the entitlement, typically the system entitlement ID from external licensing systems and third party vendors.

deviceTypestring

Type of device that this entitlement applies to, determining the category of hardware or software that can use this license.

Enum"IOT_CTRL""UNASSIGNED_DEVICE_TYPE""WIFI""LTE""SWITCH""ANALYTICS""RWG""EDGE""VIRTUAL_EDGE""APSW"

effectiveDatestring(date-time)

Date when the entitlement becomes active and can be used, marking the start of the license validity period.

expirationDatestring(date-time)

Date when the entitlement expires and is no longer valid for use, marking the end of the license validity period.

quantityinteger(int64)

Number of licenses granted by this entitlement, representing the quantity of devices or users that can use this license.

skustring

Stock keeping unit identifier for the license, uniquely identifying the product and license type in the system.

skuTierstring

Tier classification providing additional product hierarchy information for the license.

licenseNamestring

Human-readable name of the license, providing a descriptive title for the entitlement.

licenseDescstring

Detailed description of the license, providing additional information about the entitlement's purpose and features.

emailStagestring

Current stage of email notifications for the license, tracking the life cycle stage for notification purposes.

mspSkuboolean

Flag indicating whether this entitlement is an MSP (Managed Service Provider) SKU, used for filtering MSP specific licenses.

deviceSubTypestring

Device subtype classification providing additional categorization beyond the main device type.

almboolean

Flag indicating whether this entitlement is managed by ALM (application license management) system.

almLicenseTypestring

Specific license type classification, providing additional categorization for application license management.

Enum"UNKNOWN""APSW""URLF""EDGE_SECS""EDGE_SECL""SLTN_TOKEN"

almActivationIdstring

Activation identifier used for license activation and tracking within the application license management system.

almSoEntQuantityinteger(int64)

Sales order entitlement quantity, representing the total quantity allocated from the sales order in the ALM system.

almUsedQuantityinteger(int64)

Used quantity, indicating how many licenses from this entitlement are currently in use within the ALM system.

tempLicenseboolean

Flag indicating whether this is a temporary license, determined by ALM status, SKU pattern, and device type.

r1Skuboolean

Flag indicating whether this entitlement uses an R1 SKU format, determined by specific SKU naming patterns.

graceEndDatestring(date-time)

Grace period end date for the entitlement, calculated based on expiration date plus grace duration, with special handling for temporary and assigned licenses.

assignedLicenseboolean

Flag indicating whether this entitlement is an assigned license, typically generated by entitlement assignment service for MSP assignments.

extendedLicensesAssignmentboolean

Flag indicating whether this entitlement represents an extended licenses assignment, identified by specific SKU suffix patterns.

historicalboolean

Flag indicating whether this entitlement is historical (expired), determined by checking expiration status without grace period.

parentIdstring

The identifier of the parent entity in the entity hierarchy. Returns null for top level entities that have no parent.

]

Response

application/json

[
  {
    "id": "string",
    "createdDate": "2019-08-24T14:15:22Z",
    "updatedDate": "2019-08-24T14:15:22Z",
    "externalId": "string",
    "deviceType": "IOT_CTRL",
    "effectiveDate": "2019-08-24T14:15:22Z",
    "expirationDate": "2019-08-24T14:15:22Z",
    "quantity": 0,
    "sku": "string",
    "skuTier": "string",
    "licenseName": "string",
    "licenseDesc": "string",
    "emailStage": "string",
    "mspSku": true,
    "deviceSubType": "string",
    "alm": true,
    "almLicenseType": "UNKNOWN",
    "almActivationId": "string",
    "almSoEntQuantity": 0,
    "almUsedQuantity": 0,
    "tempLicense": true,
    "r1Sku": true,
    "graceEndDate": "2019-08-24T14:15:22Z",
    "assignedLicense": true,
    "extendedLicensesAssignment": true,
    "historical": true,
    "parentId": "string"
  }
]

Retrieve MSP bulk license poolsDeprecated

Request

Retrieves all MSPs bulk entitlements for the authenticated tenant. MSP bulk entitlements are large license pools that MSPs purchase and can then allocate to their customer tenants through assignments. Each entitlement includes details such as device type, SKUs, quantity, effective date, expiration date, and trial status. The response returns a list of MspEntitlement objects containing all bulk licenses available to the MSP. This method will be removed no sooner than 08/31/2026. The following endpoint '/entitlements/query' can be used for this content.

No request payload

Responses

Bodyapplication/jsonArray [

idstring

deviceTypestring

The category of device this entitlement applies to (e.g., AP for access points, SW for switches). This is a hierarchical categorization where device types can have multiple subtypes. Derived from the licenseType for database efficiency.

Enum"MSP_WIFI""MSP_SWITCH""MSP_EDGE""MSP_APSW""MSP_SLTN_TOKEN"

deviceSubTypestring

The specific subtype or variant within the device type category (e.g., Indoor AP, Outdoor AP). Provides granular categorization of devices covered by this entitlement. Derived from the licenseType.

skustring

SKU (stock keeping unit) identifier for this entitlement as assigned by the licensing system. Used for product identification, ordering, and inventory management. May contain suffixes like '-TEMP' for trial licenses or 'TMP090' for temporary entitlements.

Example: "APSW-MSP100-001"

skuTierstring

Service tier or level associated with this SKU (e.g., Bronze, Silver, Gold, Platinum). Indicates the service level and feature set included with the entitlement. Optional field that may not be present for all SKUs.

Example: "Gold"

quantityinteger(int64)

Total number of licenses available in this MSP entitlement pool. This represents the bulk quantity that the MSP can allocate to their customer tenants through assignments. Must be a positive number.

Example: 1000

effectiveDatestring(date-time)

Date and time when this entitlement becomes active and can start being used or assigned. Entitlements cannot be used before this date. Typically set to the purchase or contract start date.

Example: "2024-01-01T00:00:00Z"

expirationDatestring(date-time)

Date and time when this entitlement expires and can no longer be used or assigned. For API responses, this is returned as 23:59:59 on the expiration day (entitlements are valid all day on the expiration date). Internally stored as the exact date from the licensing system.

Example: "2024-12-31T23:59:59Z"

lastNotificationDatestring(date-time)

Date when the most recent expiration notification was sent to the tenant for this entitlement. Used to track notification history and prevent duplicate notifications. Stored as date value without time in UTC timezone.

Example: "2024-11-30"

almboolean

Indicates whether this is an ALM (advanced license management) entitlement. ALM entitlements have additional features and management capabilities compared to standard entitlements. When true, additional ALM fields like activation ID and sales order entitlement quantity may be populated.

Example: false

almActivationIdstring

Activation identifier for ALM (advanced license management) entitlements. This ID is used to track and manage ALM license activations. Only present and relevant when the 'alm' field is true.

Example: "ALM-ACT-123456"

almSoEntQuantityinteger(int64)

SO (sales order) entitlement quantity for ALM licenses. Represents the quantity specified in the sales order for this ALM entitlement. Only populated for ALM entitlements when 'alm' field is true.

Example: 500

isR1Skustring

This flag helps identify entitlements that are part of the ruckus one platform.

Example: true

statusstring

Enum"FUTURE""VALID""EXPIRED"

r1Skuboolean

This flag helps identify entitlements that are part of the ruckus one platform.

Example: true

isTrialboolean

Indicates whether this is a trial/temporary MSP entitlement. Trial entitlements are temporary evaluation licenses that allow MSPs to test functionality before purchasing full licenses. Determined by checking if the SKU ends with '-TEMP' or contains 'TMP090'. When true, this is a trial entitlement; when false, it's a standard purchased entitlement.

Example: false

]

Response

application/json

[
  {
    "id": "string",
    "deviceType": "MSP_WIFI",
    "deviceSubType": "string",
    "sku": "APSW-MSP100-001",
    "skuTier": "Gold",
    "quantity": 1000,
    "effectiveDate": "2024-01-01T00:00:00Z",
    "expirationDate": "2024-12-31T23:59:59Z",
    "lastNotificationDate": "2024-11-30",
    "alm": false,
    "almActivationId": "ALM-ACT-123456",
    "almSoEntQuantity": 500,
    "isR1Sku": true,
    "status": "FUTURE",
    "r1Sku": true,
    "isTrial": false
  }
]

Sync MSP entitlement summariesDeprecated

Request

Retrieves MSPs entitlement summaries with an optional refresh capability. When called without the 'refresh' parameter or with 'refresh=false', returns cached summary data including all MSPs bulk entitlements, expiration banners, and aggregated summaries by device type. When called with 'refresh=true', initiates a synchronization with external licensing systems to update entitlement data from the source, then returns a 202 accepted response with an activity tracking link to monitor the refresh progress. After refresh completes, call this endpoint again without the refresh parameter to retrieve the updated summaries from cache. This method will be removed no sooner than 08/31/2026. The following endpoint '/entitlements/utilizations/query' can be used for this content.

Query

refreshboolean

No request payload

Responses

Success

Bodyapplication/json

mspEntitlementsArray of objects(MspEntitlement)

List of detailed MSP entitlement records retrieved from the external license system. Each entitlement represents a license pool with complete details including SKU, quantity, dates, and device associations. This is the primary data refreshed during synchronization operations.

mspEntitlementSummariesArray of objects(MspEntitlementSummary)

Collection of aggregated entitlement summaries grouped by license type and expiration characteristics. Provides summary statistics and remaining capacity calculations derived from the detailed entitlements. Used for dashboard displays and quick availability checks without processing individual entitlement records.

mspEntitlementBannersArray of objects(BannerInformation)

Collection of banner notifications generated based on the refreshed entitlement data. Contains alerts for expiring licenses, capacity warnings, and compliance issues requiring administrator attention. Banners are derived from analyzing the refreshed entitlements for conditions that need visibility.

Response

application/json

{
  "mspEntitlements": [
    { … }
  ],
  "mspEntitlementSummaries": [
    { … }
  ],
  "mspEntitlementBanners": [
    { … }
  ]
}

Get Entitlement SummariesDeprecated

Request

Retrieves summarized entitlement utilization data for the authenticated tenant, providing an overview of license usage and availability. This method will be removed no sooner than 08/31/2026. The following endpoint '/entitlements/utilizations/query' can be used for this content.

Query

refreshboolean

typestring

Filter by device type (optional). If device agnostic sku feature is enabled, all device types will be treated as APSW except ANALYTICS.

Enum"IOT_CTRL""UNASSIGNED_DEVICE_TYPE""WIFI""LTE""SWITCH""ANALYTICS""RWG""EDGE""VIRTUAL_EDGE""APSW"

licenseTypestring

Filter by license type (optional)

Enum"UNKNOWN""APSW""URLF""EDGE_SECS""EDGE_SECL""SLTN_TOKEN"

No request payload

Responses

Returns the entitlement summary. The response is actual in case when the refresh request parameter value is false

Bodyapplication/json

entitlementsArray of objects(Entitlement)

List of entitlement objects containing detailed license information including quantities, dates, SKUs, and device types.

summaryArray of objects(EntitlementOperationInfo)

Collection of entitlement operation summaries providing aggregated license information, usage statistics, and compliance details.

bannersArray of objects(LicenseBannerDto)

Collection of license banner notifications containing alerts, warnings, and informational messages related to license status, expiration, and compliance.

Response

application/json

{
  "entitlements": [
    { … }
  ],
  "summary": [
    { … }
  ],
  "banners": [
    { … }
  ]
}

Get BannersDeprecated

Request

Retrieves entitlement banner notifications for the authenticated tenant. This method will be removed no sooner than 08/31/2026. The following endpoint '/entitlements/banners/query' can be used for this content.

Query

typestring

Filter by device type (Optional). If device agnostic sku feature is enabled, all device types will be treated as APSW except ANALYTICS.

Enum"IOT_CTRL""UNASSIGNED_DEVICE_TYPE""WIFI""LTE""SWITCH""ANALYTICS""RWG""EDGE""VIRTUAL_EDGE""APSW"

licenseTypestring

Filter by license type (optional)

Enum"UNKNOWN""APSW""URLF""EDGE_SECS""EDGE_SECL""SLTN_TOKEN"

No request payload

Responses

Bodyapplication/jsonArray [

typestring

Enum"INITIAL""CLOSE_TO_EXPIRATION""GRACE_PERIOD""AFTER_GRACE_PERIOD""RA_BELOW_90_PERCENT_OF_DEVICES""RA_BELOW_50_PERCENT_OF_DEVICES""RA_ONBOARD_ONLY"

almboolean

Indicates whether this banner is related to ALM (advanced license management) features and functionality.

almExtraInfoobject(AlmExtraEntitlementInfoDto)

Additional ALM entitlement information including license types, quantities, and remaining capacity for advanced license management scenarios.

multipleLicenseboolean

Indicates whether multiple license types or entitlements are involved in this banner notification scenario.

effectDatestring(date-time)

The effective date when the license condition described in this banner takes effect, such as expiration date or grace period end.

effectDaysinteger(int64)

Number of days until the effective date is reached, providing countdown information for license expiration or other time sensitive conditions.

deviceCountinteger(int64)

Total number of devices covered by the license associated with this banner, representing licensed device capacity.

deviceTypestring

Type of devices covered by this license banner, such as access points, switches, or analytics devices.

Enum"IOT_CTRL""UNASSIGNED_DEVICE_TYPE""WIFI""LTE""SWITCH""ANALYTICS""RWG""EDGE""VIRTUAL_EDGE""APSW"

licenseTypestring

License type classification indicating the specific licensing model or category applicable to this banner notification.

Enum"UNKNOWN""APSW""URLF""EDGE_SECS""EDGE_SECL""SLTN_TOKEN"

deviceSubTypestring

Specific subtype or model classification within the broader device type category, providing more granular device identification.

totalRALicenseinteger(int64)

Total number of ruckus analytics licenses available, for tracking and notifications.

totalActiveDevicesinteger(int64)

Total count of currently active devices across all device types including access points, switches, and edge devices.

]

Response

application/json

[
  {
    "type": "INITIAL",
    "alm": true,
    "almExtraInfo": { … },
    "multipleLicense": true,
    "effectDate": "2019-08-24T14:15:22Z",
    "effectDays": 0,
    "deviceCount": 0,
    "deviceType": "IOT_CTRL",
    "licenseType": "UNKNOWN",
    "deviceSubType": "string",
    "totalRALicense": 0,
    "totalActiveDevices": 0
  }
]

Get Assignment SummariesDeprecated

Request

Get summaries of MSP license assignments by device type and device subtype. This method will be removed no sooner than 08/31/2026. The following endpoint '/entitlements/utilizations/query' can be used for this content.

No request payload

Responses

Bodyapplication/jsonArray [

deviceTypestring

Primary device type classification such as access points, switches, or analytics devices for assignment categorization.

Enum"MSP_WIFI""MSP_SWITCH""MSP_EDGE""MSP_APSW""MSP_SLTN_TOKEN"

deviceSubTypestring

Specific device model or subtype within the broader device category, providing granular assignment classification when applicable.

quantityinteger(int64)

Total quantity of devices available for assignment within this device type and subtype category.

myAssignmentsinteger(int64)

Number of devices currently assigned to this MSP customer from the available quantity for capacity tracking.

courtesyMspEntitlementsUsedboolean

Flag indicating whether courtesy MSP entitlements have been utilized for this assignment summary, affecting billing and capacity calculations.

remainingDevicesinteger(int64)

Number of remaining devices available for assignment within this device type and license category after current allocations.

trialboolean

Flag indicating whether this assignment summary represents trial licenses with temporary validity and limited functionality.

licenseTypestring

License type enumeration specifying the category and classification of licenses covered by this assignment summary.

Enum"MSP_WIFI""MSP_WIFI_TEMP""MSP_ICX""MSP_ICX71L""MSP_ICX71""MSP_ICX75""MSP_ICX76""MSP_ICX78""MSP_ICX_ANY""MSP_EDGE"

]

Response

application/json

[
  {
    "deviceType": "MSP_WIFI",
    "deviceSubType": "string",
    "quantity": 0,
    "myAssignments": 0,
    "courtesyMspEntitlementsUsed": true,
    "remainingDevices": 0,
    "trial": true,
    "licenseType": "MSP_WIFI"
  }
]

Revoke Bulk AssignmentsDeprecated

Request

Revoke multiple license assignments for MSP. This method will be removed no sooner than 08/31/2026. The following endpoint '/tenants/{tenantId}/entitlements/assignments/query' can be used for this content.

Bodyapplication/jsonrequiredArray [

assignmentIdinteger(int64)required

Unique identifier of the assignment to be revoked through the bulk operation.

Example: 231

]

application/json

[
  {
    "assignmentId": 231
  }
]

Responses

No Content

Bodyapplication/json

successboolean

assignmentsArray of objects(Assignment)

Collection of license assignments associated with the operation.

errorBriefstring

Brief error classification providing quick error identification.

Enum"NO_CREATED_ASSIGNMENTS""ASSIGNMENT_CREATION_BAD_INPUT""NO_MSP_ENTITLEMENTS""MSP_ENTITLEMENTS_NOT_FOUND""INSUFFICIENT_MSP_ENTITLEMENTS""ASSIGNMENT_NOT_FOUND""TENANT_NOT_MSP""TENANT_NOT_FOUND""ENTITLEMENT_ID_NOT_FOUND""ASSIGNMENT_NOT_REVOCABLE"

errorMessagestring

Detailed error message describing the cause of the operation failure.

veobject(ValidationErrors)

Validation errors containing detailed information about invalid input parameters.

Response

application/json

{
  "success": true,
  "assignments": [
    { … }
  ],
  "errorBrief": "NO_CREATED_ASSIGNMENTS",
  "errorMessage": "string",
  "ve": {
    "object": "string",
    "objectName": "string",
    "value": "string",
    "expected": "string"
  }
}