RUCKUS ONE APIs

This document describes the RUCKUS One public APIs. All RUCKUS One API's are hosted on the mapped subdomain, "api.".

Asynchronous Workflows: In many cases, requests to create or change data is handled asynchronously. In these case the return value from the API call will be the requestId for the activity that was triggered to perform the request. The API consumer will need to:

1. Read the "requestId" from the response
2. Poll the activity service with the requestId and wait for SUCCESS using GET /api/tenant/{tenantId}/activity/{requestId}
3. GET the list of resources to find the item created

RUCKUS One API Hosts

Original R1 API Site

If you are looking for the original RUCKUS One API website, it has been removed, as the site was only be maintained until 2/28/2024.

License: RUCKUS One Privacy Policy | Terms of Service APIs published in this document are subject to strict change control by RUCKUS. As far as possible, when new versions of the Public API are published, all documented API endpoints will maintain backward compatibility. When not possible, an API endpoint will be deprecated and a replacement API or some other workaround will be provided. Support for deprecated API endpoints will continue for at least six months prior to removal in order to provide API client developers sufficient time to adopt the replacement. This document will indicate when API endpoints are deprecated along with the schedule for their removal. API client developers may discover other experimental API endpoints provided by RUCKUS One not included in this API document. RUCKUS reserves the right to change these experimental APIs without notice to API client developers.

This section is a short list of the upcoming API changes and features.

Rate Limiting

The Ruckus One API's have added rate limiting to several of the APIs. A rate limit is the number of API calls an app or user can make within a given time period. If this limit is exceeded, the app or user may be throttled. API requests made by a throttled user or app will fail. The API will return a 429 to indicate rate limiting has been encountered. Each set of APIs which have rate limiting will identify the limits for those APIs in the API information included with each API section. The rate limit is determined by three key aspects:

Ruckus One APIs will support versioning using the Content Negotiation approach, or by deprecating and replacing specific URI's. The format of the versioned content will be: "application/vnd.ruckus.v+json", in addition the most current version of a resource will be supported with "application/json". Only breaking changes will require versioning. The deprecated version will be maintained for a minimum of 6 months and the removal will only occur in March of a given year. Please be aware that current APIs always support "application/json", so changes using the versioning will transition to the latest version of the resource. Please update your use of the API, either to the latest resource, or update to the correct "application/vnd.ruckus.v+json" that you are supporting.

--

Authenticating

The RUCKUS One REST APIs use JSON Web Tokens (JWT) to secure all endpoints.

Ruckus One authentication APIs are using the OAuth2 client credentials standard APIs, as described here: https://datatracker.ietf.org/doc/html. The API will authenticate a user client and will provide the JWT token.

As part of our ongoing efforts to enhance security and efficiency, we have deprecated the use of the /token authentication API. The /token authentication API will be officially turned down on August 31, 2024. To continue accessing RUCKUS One APIs seamlessly, it is imperative that you transition to using the Java Web Token (JWT) authentication method.

How to Authenticate

Once logged into Ruckus One, the Administrator must create an "Application Token" consisting of client ID, client secret and scope, and can be found under Administration -> Account Management -> Settings.

The following endpoint will be used to authenticate and retrieve the JWT token:

Here is an example with curl:

    curl --request POST \
    --url 'https://ruckus.cloud/oauth2/token/<tenantId>' \
    --header 'content-type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id=<client id> \
    --data client_secret=<client secret>

Once you have acquired your JWT token, it must be included as "Authorization" HTTP request header of all subsequent requests. The format expected in the authentication header is "Bearer xxxxxxa". For additional information on the authentication scheme being used, please see RFC 6750 Section 2.1.

Using the API's in Delegated Mode

To access any REST API for a delegated account, correctly authenticate. Provide your JWT authentication credentials, but in addition, include the custom header with a key of "x-rks-tenantid" and value of tenant id to identify the delegated account. If the request URL specifies the "{tenantId}" as a path parameter, then this needs to be the id for the value of delegated account.

Business Entities

The following table describes the type of businesses (aka organizations) that use these API endpoints. Not all endpoints are useful for every business entity.

Entitlements/Licenses

Entitlements (aka licenses) are purchased by an account holder and entitle that account to install networking devices in their venues. After purchase, entitlements must be "activated" using the RUCKUS Support website before becoming effective for device installation. There are two classes of entitlements:

• Device entitlements, simply referred to as "entitlements", which entitle an account to provision/install one networking device per entitlement.
• MSP entitlements, used only by MSPs, are assigned to MSP-EC accounts, enabling the provision/installation of one networking device per assignment in an MSP-EC network.

As an introduction to the Wi-Fi API endpoints, a basic workflow to install and configure a Wi-Fi network is described. The order of the following steps is merely an example. The following description is not meant to be comprehensive; rather, it is meant to be a guide to get you started with API client development.

1. Create a venue for your APs. You can create as many venues as you like. Typically, one venue is created for each building in which you install APs. Or you can use a single "venue" for all the buildings on a campus; alternatively, a "venue" may be just a single floor in a multistory building, or an outdoor park.
2. Provision your APs. To provision an AP, add the AP using the "Add APs" endpoint found in the AP section. Once your APs are provisioned, physically install them. They will automatically contact and join RUCKUS One. You can physically install your APs prior to provisioning, but they will not join the network until provisioned. In order to install an AP, your account must possess activated licenses. Purchased licenses are activated on the RUCKUS Support website. Use endpoints found under the Entitlements group to manage your entitlements (aka licenses). If you do not have any activated entitlements, the "Add APs" endpoint will return an error response.
3. Verify your APs have connected to RUCKUS One. To check an AP's connection, use the "Get APs" endpoint in the "AP" API group. The API response provides the AP's connection status. If your APs are having trouble connecting, you can locally log in to your AP and use its troubleshooting utilities to diagnose the problem.
4. Create a WLAN. Use the endpoints in the "Network" API group to create a WLAN. Note that WLANs are global resources that can be activated in as many venues as you like. Simply creating a WLAN does not deploy it to APs. To deploy the WLAN, it must be "activated" on a venue. Use the endpoints in the "Network-Venue" API group for managing WLAN deployments.
5. Customize the configuration of your APs. AP configuration can be customized on three different levels:
   • All the APs in a venue can be collectively customized using endpoints in the "AP-Venue" API group. On a per-venue basis, you can customize the radio or LAN port settings of your APs, as well as enable and manage mesh networking.
   • APs can be grouped together using endpoints in the "AP" Group APIs. Each venue can have one or more AP groups; if you do not explicitly configure AP groups, all APs in a venue are members of the "default" group. Grouping APs is typically done to restrict the deployment of certain WLANs to the APs in a group rather than all the APs in a venue. You may want to do this, for example, to enable only your guest WLAN in the lobby of your venue. Also, using AP groups, WLANs can be enabled on either the 2.4-GHz or 5-GHz band instead of both bands (which is the default). Use the endpoints in the "Network-Venue" API group for managing WLAN (network) assignments to AP groups.
   • APs can be individually customized using endpoints in the "AP" API group. On a per-AP basis, you can customize an AP's radio or LAN port settings. Individual AP configurations override group-level and venue-level configurations.
6. Protect your network. Enable rogue AP detection, configure rogue AP classification policies, and view reports on detected rogue APs. Use the endpoints in the "AP-Venue" API group for this purpose. Note: Once an administrator is informed of the presence of a rogue AP, they can take steps to manually remove it.
7. Add sophistication to your WLAN. Use the endpoints in the "L2ACL Policy", "L3ACL Policy", "Device Policy", and "Application Policy" API groups to create and manage WLAN policies that manage your wireless clients (end-user devices) and their connections to online services more effectively.
8. Add new services to your wireless network. Services such as Wi-Fi calling and RUCKUS Location Services (aka vSPoT) are available; they can be configured and managed using the endpoints in their respective API groups. APs can provide DHCP service with sufficient scale for small offices or branch offices; use the endpoints in the "DHCP Configuration Service Profile" to configure the service and endpoints in "Update DHCP Service Profile Settings of This Venue" to activate them on your venues.
9. Manage your network's client devices. If you have a guest WLAN that uses guest passes, you can create and manage guest users with endpoints in the "Guest User" API group. If you find client devices that should not be on your network, you can disconnect them using an endpoint in the "Clients Control" API.

On RUCKUS One, manage ICX switches deployed with Fastiron firmware version 8.0.95. In this API document, you may read about topics unfamiliar to you; for example, ACLs, LAGs, trusted ports, etc. A thorough treatment of these topics is beyond the scope of this document. However, these topics and more are covered in detail in the Fastiron configuration guides. Links to configuration guides for Fastiron firmware are provided in the following table.

As part of the Property management feature, RUCKUS One administrators can create units for each Venue. The Resident Portal APIs enable the unit resident to manage their own devices, DPSKs, and guest access, and their contact information.

The Resident Portal APIs, categorized under API Group "Resident Portal" offer access to device and owner information for a single unit, as defined and created in the Venue Property Management Feature. These APIs serve as a foundation for creating a custom Resident Portal. Both the Resident Portal and the Resident Portal APIs can be disabled with the RUCKUS One UI, or through the Property Configuration APIs, "Selectively Update Property Configuration".

Authentication to the resident portal are provided by a unique key associated to the unit and not the administrative credentials. Consequently, the API provides information and limited control only of aspects respective of the unit. Both the Administrator and the Resident Portal APIs can be used to reset the unique key linked to a particular unit.

Login into the API per Unit. ETo access the Resident portal, APIs on a per unit bases, you will utilize the specific unique key associated to the unit. To initiate this process, make use of the "Resident Portal Login API". This API will return a JSON Web Token (JWT) that will be used in subsequent Resident Portal API calls. The following API groups can be accessed by this mechanism:

• Resident Portal Login API: The login APIs.
• Resident Portal Configuration: Provides details for the venue that can be presented to the unit owner.
• Resident Portal Unit API: Provides unit specific details and allows management of certain properties.
• Resident Portal UI Configuration: Provides details on the resident portal UI configuration, like logo, and title information.

View platform information. Note: this group of endpoints is used to view activities data. They don't provide the means to manage configuration.

APIs for Certificate Authority Management.