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 Entitlements Utilization Summaries

Request

Retrieve entitlement usage details. Usage summaries provide information on the number of entitlements used and active devices.

Headers

Content-Typestringrequired

Body

required

filtersobject(DynamicQueryPayloadFilterDto)

Filter criteria for querying entitlement utilization.

{
  "filters": {
    "licenseType": [ … ],
    "isTrial": false,
    "status": [ … ],
    "isAssignedLicense": false,
    "usageType": "SELF, ASSIGNED, UNKNOWN",
    "expirationDateRange": { … },
    "sku": "[A-Z]+-[A-Z]+-[A-Z]+-[A-Z]+[0-9]$",
    "skuTier": "Platinum, Gold, Silver",
    "renewable": false
  }
}

Responses

Returns entitlement utilization query response for SELF usage type or assigned entitlement summaries response for ASSIGNED usage type.

Body

dataArray of objects

Response

{
  "data": [
    { … }
  ]
}

Get Entitlements

Request

Retrieves all purchased entitlements for the authenticated tenant. Purchased entitlements represent the licenses, subscriptions, and service rights that an organization has acquired through purchases, contracts, or promotions. Each entitlement includes details about the license type, stock keeping unit (SKU), quantity, effective dates, expiration dates, device compatibility, and current usage status.

What constitutes a purchased entitlement: subscription licenses with defined quantities and terms, promotional licenses granted for trials or special offers, perpetual licenses with unlimited duration, device specific licenses (access points, switches, analytics), and feature specific entitlements (security, guest access, location services).

Available filters: filter by license type (subscription, trial, promotional), device type (wifi, switch, analytics, edge), license status (active, expired, pending), date ranges (effective date, expiration date), and SKU identifiers. Supports pagination, sorting, and field selection to customize the response.

Response: returns a paginated list of entitlement objects with license details, quantities, dates, usage metrics, and associated device types.

Query

excludeContentboolean

Bodyapplication/vnd.ruckus.v1+jsonrequired

defaultPageSizeinteger(int32)

Default number of records per page to use when pageSize is not explicitly specified or is invalid.

sortFieldstring

Field name to use for sorting the query results in ascending or descending order.

sortOrderstring

Sort order direction for the specified sort field, typically 'ASC' for ascending or 'DESC' for descending.

pageinteger(int32)

pageSizeinteger(int32)

Number of records to return per page for pagination, with automatic fallback to default if invalid.

fieldsArray of stringsunique

Set of specific field names to include in the query response, enabling selective data retrieval.

filtersobject(DynamicQueryPayloadFilterDto)

Filter criteria object containing various conditions to narrow down query results based on specific parameters.

application/vnd.ruckus.v1+json

{
  "defaultPageSize": 0,
  "sortField": "string",
  "sortOrder": "string",
  "page": 0,
  "pageSize": 0,
  "fields": [
    "string"
  ],
  "filters": {
    "licenseType": [ … ],
    "isTrial": false,
    "status": [ … ],
    "isAssignedLicense": false,
    "usageType": "SELF, ASSIGNED, UNKNOWN",
    "expirationDateRange": { … },
    "sku": "[A-Z]+-[A-Z]+-[A-Z]+-[A-Z]+[0-9]$",
    "skuTier": "Platinum, Gold, Silver",
    "renewable": false
  }
}

Responses

success.

Body

fieldsArray of stringsunique

Set of field names that were requested to be included in the response data.

totalCountinteger(int64)

Total number of records available that match the query criteria, used for pagination calculations.

pageinteger(int32)

pageSizeinteger(int32)

Maximum number of records returned in this response page.

objectIdstring

Unique identifier for the primary object or entity associated with this query response.

dataArray of objects

errorsArray of objects(ErrorDto)

List of errors that occurred during processing, if any.

subsequentQueriesArray of objects(SubsequentQuery)

List of additional API calls that can be made to retrieve related or supplementary data.

Response

{
  "fields": [
    "string"
  ],
  "totalCount": 0,
  "page": 0,
  "pageSize": 0,
  "objectId": "string",
  "data": [
    null
  ],
  "errors": [
    { … }
  ],
  "subsequentQueries": [
    { … }
  ]
}

Query License Mileage Report

Request

Mileage reports offer clear insights into how licenses have been consumed and released across different periods.

Request payload structure: accepts a mileage request object containing:

license type filters
pagination parameters (page size, page number)

Available filters:

filter by specific license types
filter by date range (if applicable)
additional filters based on business requirements

Response format: returns a mileage response containing a list of mileage report entries. each entry provides:

monthly usage data
breakdown of license increases and decreases
key metrics reflecting license life cycle changes.

Body

required

pageinteger(int32)

The page number to be returned, 1 based, default 1.

Example: 1

pageSizeinteger(int32)

The page number to be returned, default 20.

Example: 30

filtersobject(CalculatorFilterRequestDto)required

Filter criteria for the request.

filters.usageTypestringrequired

Type of usage. Possible values: SELF (default), ASSIGNED, UNKNOWN.

Enum"SELF""ASSIGNED""UNKNOWN"

Example: "SELF"

filters.licenseTypestringrequired

Type of entitlement license to calculate.

Example: "APSW"

filters.isTrialboolean

Indicates whether to calculate availability for trial/temporary licenses. When true, the calculation considers only trial license entitlements which are typically temporary evaluation licenses. When false, the calculation considers standard purchased licenses. This flag helps distinguish between trial and production license availability in the entitlement calculation.

Example: true

{
  "page": 1,
  "pageSize": 30,
  "filters": {
    "usageType": "SELF",
    "licenseType": "APSW",
    "isTrial": true
  }
}

Responses

Success

Body

statusstring

Status of the response.

Example: "success"

messagestring

Message providing additional details about the response.

Example: "Object created/updated successfully."

pageinteger(int32)

Current page number in the paginated result set.

pageSizeinteger(int32)

Number of records returned per page for pagination control.

totalCountinteger(int64)

Total number of records available across all pages.

dataArray of objects(MileageDataDto)

Data object containing license details.

Response

{
  "status": "success",
  "message": "Object created/updated successfully.",
  "page": 0,
  "pageSize": 0,
  "totalCount": 0,
  "data": [
    { … }
  ]
}

Get Compliance

Request

Retrieve detailed license availability reports that calculate how many licenses are currently available for assignment or consumption. This endpoint performs real-time calculations to determine remaining license capacity by analyzing purchased entitlements, active assignments, expired licenses, and reserved allocations. Availability reports are essential for capacity planning and preventing over allocation.

Bodyapplication/vnd.ruckus.v1+jsonrequired

filtersobject(LicenseComplianceFilter)

Filter criteria object containing parameters to narrow down compliance query results based on license types and status.

application/vnd.ruckus.v1+json

{
  "filters": {
    "licenseType": [ … ],
    "complianceType": "SELF"
  }
}

Responses

success

Bodyapplication/vnd.ruckus.v1+json

compliancesArray of objects(TenantLicenseCompliance)

List of license compliance details for each tenant, including license usage statistics, device compliance status, and license assignment information.

Response

application/vnd.ruckus.v1+json

{
  "compliances": [
    { … }
  ]
}

Get Entitlements Banners

Request

Retrieve entitlement banner data for display in the user interface. Banners are visual notifications that alert administrators about critical license conditions requiring attention. They provide information about entitlements that are either near their expiry or have expired, helping prevent service disruptions. Version application/vnd.ruckus.v1+JSON will be removed no sooner than 08/31/2026. application/JSON and application/vnd.ruckus.v1.1+JSON are now available.

Bodyapplication/vnd.ruckus.v1+jsonrequired

filtersobject(Filters)

Filter criteria for determining which entitlement banners to display, containing license type specifications and usage type preferences.

application/vnd.ruckus.v1+json

{
  "filters": {
    "licenseType": [ … ],
    "usageType": "string"
  }
}

Responses

success

Bodyapplication/vnd.ruckus.v1+json

dataArray of objects(EntitlementBannerInfo)

Response

application/vnd.ruckus.v1+json

{
  "data": [
    { … }
  ]
}

Query Availability Reports

Request

This endpoint allows you to query availability reports for entitlements.

Bodyapplication/vnd.ruckus.v1+jsonrequired

effectiveDatestring^\d{4}-\d{2}-\d{2}$required

Start date from which the license is valid.

Example: "2024-01-22"

expirationDatestring^\d{4}-\d{2}-\d{2}$

End date until which the license is valid. Required if operator max quantity is selected.

Example: "2025-02-21"

quantityinteger(int32)

Number of licenses available. Required if operator max period is selected.

Example: 5

operatorstringrequired

Operator to be used.

Enum"MAX_QUANTITY""MAX_PERIOD"

Example: "MAX_QUANTITY"

filtersobject(CalculatorFilterRequestDto)required

Filter criteria for the request.

filters.usageTypestringrequired

Type of usage. Possible values: SELF (default), ASSIGNED, UNKNOWN.

Enum"SELF""ASSIGNED""UNKNOWN"

Example: "SELF"

filters.licenseTypestringrequired

Type of entitlement license to calculate.

Example: "APSW"

filters.isTrialboolean

Example: true

application/vnd.ruckus.v1+json

{
  "effectiveDate": "2024-01-22",
  "expirationDate": "2025-02-21",
  "quantity": 5,
  "operator": "MAX_QUANTITY",
  "filters": {
    "usageType": "SELF",
    "licenseType": "APSW",
    "isTrial": true
  }
}

Responses

Success

Body

statusstring

Status of the response.

Example: "success"

messagestring

Message providing additional details about the response.

Example: "Object created/updated successfully."

dataobject(CalculatorDataDto)required

Data object containing license details

data.effectiveDatestringrequired

Effective date of the license.

Example: "2024-01-22"

data.expirationDatestring

Expiration date of the license.

Example: "2024-02-21"

data.quantityinteger(int64)

Total number of licenses available.

Example: 5

data.licenseTypestring

Type of license being calculated.

Example: "APSW"

data.skuTierstring

SKU tier level for the license.

Example: "Silver"

data.isTrialbooleanrequired

Indicates whether this calculation is for trial/temporary licenses. Trial licenses are temporary evaluation licenses that allow customers to test functionality before purchasing full licenses. When true, the calculation considers trial license availability; when false, it considers standard purchased license availability. This distinction affects which entitlements are included in the availability calculation.

Example: false

Response

{
  "status": "success",
  "message": "Object created/updated successfully.",
  "data": {
    "effectiveDate": "2024-01-22",
    "expirationDate": "2024-02-21",
    "quantity": 5,
    "licenseType": "APSW",
    "skuTier": "Silver",
    "isTrial": false
  }
}

Query License Attention Notes

Request

Queries license attention notes, which are alerts and notifications related to license status that require administrator attention. Attention notes are automatically generated for important license events such as upcoming change in licensing system.

Query

excludeContentboolean

Default false

Body

required

sortFieldstring

Sorting field, it can be any of the fields of attention notes.

Example: "startDate"

sortOrderstring

Sorting order, default is ascending order if missing.

Enum"ASC""DESC"

Example: "DESC"

pageinteger(int32)

Page number, 1 based, default is 1 if missing.

Example: 1

pageSizeinteger(int32)

Page size, default is 20 if missing.

Example: 30

fieldsArray of stringsunique

Fields to return, all fields will be returned if missing.

Example: ["summary","details"]

filtersobject(AttentionNoteQueryFilterDto)

Filter criteria for attention note queries, containing type, tenant type, status, and other filtering options to narrow down search results.

{
  "sortField": "startDate",
  "sortOrder": "DESC",
  "page": 1,
  "pageSize": 30,
  "fields": [
    "summary",
    "details"
  ],
  "filters": {
    "type": [ … ],
    "tenantType": [ … ],
    "status": [ … ],
    "enabled": true,
    "licenseCheck": true
  }
}

Responses

Success

Body

fieldsArray of stringsunique

Set of field names that were requested to be included in the response data.

totalCountinteger(int64)

Total number of records available that match the query criteria, used for pagination calculations.

pageinteger(int32)

pageSizeinteger(int32)

Maximum number of records returned in this response page.

objectIdstring

Unique identifier for the primary object or entity associated with this query response.

dataArray of objects

errorsArray of objects(ErrorDto)

List of errors that occurred during processing, if any.

subsequentQueriesArray of objects(SubsequentQuery)

List of additional API calls that can be made to retrieve related or supplementary data.

Response

{
  "fields": [
    "string"
  ],
  "totalCount": 0,
  "page": 0,
  "pageSize": 0,
  "objectId": "string",
  "data": [
    { … }
  ],
  "errors": [
    { … }
  ],
  "subsequentQueries": [
    { … }
  ]
}

Update Entitlements

Request

Synchronizes entitlements by triggering a refresh of license data from external licensing systems. This operation fetches the latest license purchases, renewals, and modifications, then updates the local entitlement cache to reflect current entitlements.

What is synchronized: new license purchases, license quantity changes, expiration date updates, license type modifications, subscription renewals.

Prerequisites: the tenant must have an active entitlement ID and at least one active subscription.

Bodyapplication/vnd.ruckus.v1+jsonrequired

statusstring

refreshTypestring

Type of refresh operation to perform during synchronization, determining the scope and method of the entitlement data refresh.

Enum"FULL""DELTA""PAGINATED"

Example: "PAGINATED"

usageTypestringDeprecated

Usage type for entitlement synchronization, specifying the context of the sync operation; deprecated and not used in V2.

application/vnd.ruckus.v1+json

{
  "usageType": "string",
  "status": "string",
  "refreshType": "PAGINATED"
}

Responses

Sync entitlements

Body

linkstring(uri)

URI link for tracking or retrieving the status of the accepted request.

descstring

Human-readable description providing details about the accepted request, its purpose, and expected processing outcome.

requestIdstring

Unique identifier assigned to track the accepted request throughout its processing life cycle, enabling status monitoring and correlation with logs.

Response

{
  "link": "http://example.com",
  "desc": "string",
  "requestId": "string"
}

Get Entitlement Usage Report

Request

Get the entitlement usage report.

Query

licenseTypestring

Specific license type if the tenant is an ALM tenant, valid value: MSP_APSW (default), MSP_URLF, MSP_EDGE_SECS, MSP_EDGE_SECL

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

startDatestring

The first date included in the usage report, for example, startDate=2024-01-15; if omitted, the startDate is set to last month's first date.

endDatestring

The end date included in the usage report, for example, endDate=2024-01-31; if omitted, the endDate is set to last month's last date.

monthstring

month=MM

yearstring

year=YYYY

mspEcTenantIdstring

Specific MSP EC tenant ID

deviceDetailsboolean

True to include device detail in the report. False to exclude device detail in the report.

Default false

pageinteger(int32)

Page number for the daily reports. If missing or value 0 means no pagination, all daily reports will be returned.

Default 0

pageSizeinteger(int32)

Page size for the daily reports, default is 5, valid only if page is given

Default 5

Headers

Content-Typestringrequired

No request payload

Responses

Success

Body

mspNamestring

Name of the managed service provider generating this usage report for identification and billing purposes.

licenseTypestring

Device license type enumeration specifying the category of devices covered in this usage report for billing classification.

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

reportLicenseTypeNamestring

Human-readable license type name used in report generation and CSV export for display purposes.

requestStartDatestring(date)

Original start date requested by the user for the usage report period, using ISO date format (example: 2025-11-21).

requestEndDatestring(date)

Original end date requested by the user for the usage report period, using ISO date format (example: 2025-11-30).

reportStartDatestring(date)

Actual start date used in the generated report, which may differ from requested date due to data availability, using ISO date format (example: 2025-11-01).

reportEndDatestring(date)

Actual end date used in the generated report, which may differ from requested date due to data availability, using ISO date format (example: 2025-11-30).

totalDaysInReportinteger(int64)

Total number of days covered in this usage report, calculated from the actual report start and end dates.

grandTotalAssignmentDaysinteger(int64)

Grand total of all device assignment days across all device types and customers for billing calculations.

grandTotalDeviceDaysinteger(int64)

Grand total of all operational device days across all device types for capacity planning and utilization analysis.

totalAssignmentDaysByDeviceArray of objects(AssignmentDaysByDevice)

Detailed breakdown of assignment days grouped by device type and subtype for granular billing analysis and customer reporting.

totalDeviceDaysByDeviceArray of objects(DeviceDaysByDevice)

Detailed breakdown of operational device days grouped by device type and subtype for capacity planning and utilization tracking.

dailyReportArray of objects(DailyReport)

Collection of daily usage reports providing daily breakdown of device assignments, customer activity, and operational metrics for detailed analysis.

pageinteger(int32)

Current page number in the paginated result set, starting from 0 for pagination control.

totalPagesinteger(int32)

Total number of pages available in the complete result set for pagination navigation.

dailyReportPerPageinteger(int32)

Number of daily reports included per page for pagination sizing and performance optimization.

Response

{
  "mspName": "string",
  "licenseType": "MSP_WIFI",
  "reportLicenseTypeName": "string",
  "requestStartDate": "2019-08-24",
  "requestEndDate": "2019-08-24",
  "reportStartDate": "2019-08-24",
  "reportEndDate": "2019-08-24",
  "totalDaysInReport": 0,
  "grandTotalAssignmentDays": 0,
  "grandTotalDeviceDays": 0,
  "totalAssignmentDaysByDevice": [
    { … }
  ],
  "totalDeviceDaysByDevice": [
    { … }
  ],
  "dailyReport": [
    { … }
  ],
  "page": 0,
  "totalPages": 0,
  "dailyReportPerPage": 0
}

Manage Entitlements

Operations

Entitlements (v0.2.0)

Entitlement

Get Entitlements Utilization Summaries

RequestExpand all

Responses

Get Entitlements

RequestExpand all

Responses

Query License Mileage Report

RequestExpand all

Responses

Get Compliance

RequestExpand all

Responses

Get Entitlements Banners

RequestExpand all

Responses

Query Availability Reports

RequestExpand all

Responses

Query License Attention Notes

RequestExpand all

Responses

Update Entitlements

Request

Responses

Get Entitlement Usage Report

Request

Responses

Manage Entitlements

Request

Request

Request

Request

Request

Request

Request