Getting started with WSO2 Device Cloud APIs

Introduction
WSO2 Device Cloud is the latest addition to WSO2’s Cloud offering. It aims to provide device integration and management to rest of the WSO2 cloud. As of now, it allows integrating and managing Android & iOS powered devices. Device Cloud offers an UI to manage connected devices.

Screen Shot 2017-06-02 at 11.59.30 PM.png
Fig 1: Device Management Dashboard Page on Device Cloud

Screen Shot 2017-06-03 at 12.04.45 AM.png

Fig 2: Listing of all registered devices

But the functionality is not limited to a web application. All device management capabilities are offered as OAuth2 protected REST APIs as well.  

This tutorial explains how to make programmatic use of these APIs. In order to proceed with examples, you need to have a WSO2 Cloud account (https://cloud.wso2.com).  If you do not possess an account please use the following url to register one.


 API Store
All apis related to device management are available in the API Store part of WSO2 Cloud.

Screen Shot 2017-06-02 at 11.44.07 PM.png

These APIs fall under two categories.

  1. Device Management APIs
    The API on the IoT server which is used to manage the device such as “getDevices”, “getPolicies”. Device types related admin services such as executing an operation on a devices also include in this category. These are available for both device types supported (ios and android).
    Call direction; Mgt App -> API -> Device
  2. Device Agent APIs
    The API on the IoT server that the device agent calls. Android devices will invoke “Android Device Management” (getPendingOperations) and iOS devices communications happens without subscribing and different from android communication flow. And iOS uses different authorization mechanism than Android.
    Call direction; Device -> API -> Device plugin

 Device Management APIs

APIs related to administrative tasks are available under the tag “device_management”


Device Agent APIs



How to obtain an access token?

All the admin and device APIs (Except iOS device → server communication apis) are protected with OAuth, therefore to invoke any API, request should consist the oauth header.

Please follow the following steps to obtain the token.

Step 1:

First step is to create an oauth application to call admin apis. This will return you client_id and client_secret.

curl -k -X POST https://gateway.api.cloud.wso2.com/api-application-registration/register -H 'authorization: Basic [Base64encode(username@company_name:password)]' -H 'content-type: application/json' -d '{ "applicationName":"TestApplication", "isAllowedToAllDomains":false, "tags":["device_management"]}'

Please refer the following example. If your username is “example@wso2.com” and your company name is “wso2” and password is “123456”, curl request will be as follows.

Step 1  Example:
curl -k -X POST https://gateway.api.cloud.wso2.com/api-application-registration/register -H 'authorization: Basic ZXhhbXBsZUB3c28yLmNvbUB3c28yOjEyMzQ1Ng==' -H 'content-type: application/json' -d '{ "applicationName":"TestApplication", "isAllowedToAllDomains":false, "tags":["device_management"]}'

Response will be as follows

{"client_secret":"xxxxxxxxxxxxxxxxxxxx","client_id":"xxxxxxxxxxxxxxxxxxxx"}

Step 2 :

Second step is to get the access token in order to invoke APIS. Please use the following commands to retrieve the access token. Scopes used in this commands represents the permissions of the user to invoke the apis. If the invoking user does not have relevant permission, it will only return an oauth token with related permissions only. You can pick and choose the scopes you need to use.

curl -v -k -d "grant_type=password&username={username@company_name}&password={password}&scope=perm:sign-csr perm:admin:devices:view perm:roles:add perm:roles:add-users perm:roles:update perm:roles:permissions perm:roles:details perm:roles:view perm:roles:create-combined-role perm:roles:delete perm:dashboard:vulnerabilities ………………..." -H "Authorization: Basic [Base64encode(client_id:client_secret)]" -H "Content-Type: application/x-www-form-urlencoded" https://gateway.api.cloud.wso2.com/token

Please refer following example.

Step 2 Example:


curl -v -k -d "grant_type=password&username=example@wso2.com@wso2&password=123456&scope=perm:sign-csr perm:admin:devices:view perm:roles:add perm:roles:add-users perm:roles:update perm:roles:permissions perm:roles:details perm:roles:view perm:roles:create-combined-role perm:roles:delete perm:dashboard:vulnerabilities perm:dashboard:non-compliant-count perm:dashboard:non-compliant perm:dashboard:by-groups perm:dashboard:device-counts perm:dashboard:feature-non-compliant perm:dashboard:count-overview perm:dashboard:filtered-count perm:dashboard:details perm:get-activity perm:devices:delete perm:devices:applications perm:devices:effective-policy perm:devices:compliance-data perm:devices:features perm:devices:operations perm:devices:search perm:devices:details perm:devices:update perm:devices:view perm:view-configuration perm:manage-configuration perm:policies:remove perm:policies:priorities perm:policies:deactivate perm:policies:get-policy-details perm:policies:manage perm:policies:activate perm:policies:update perm:policies:changes perm:policies:get-details perm:users:add perm:users:details perm:users:count perm:users:delete perm:users:roles perm:users:user-details perm:users:credentials perm:users:search perm:users:is-exist perm:users:update perm:users:send-invitation perm:admin-users:view perm:groups:devices perm:groups:update perm:groups:add perm:groups:device perm:groups:devices-count perm:groups:remove perm:groups:groups perm:groups:groups-view perm:groups:share perm:groups:count perm:groups:roles perm:groups:devices-remove perm:groups:devices-add perm:groups:assign perm:device-types:features perm:device-types:types perm:applications:install perm:applications:uninstall perm:admin-groups:count perm:admin-groups:view perm:notifications:mark-checked perm:notifications:view perm:admin:certificates:delete perm:admin:certificates:details perm:admin:certificates:view perm:admin:certificates:add perm:admin:certificates:verify perm:ios:enroll perm:ios:view-device perm:ios:apn perm:ios:ldap perm:ios:enterprise-app perm:ios:store-application perm:ios:remove-application perm:ios:app-list perm:ios:profile-list perm:ios:lock perm:ios:enterprise-wipe perm:ios:device-info perm:ios:restriction perm:ios:email perm:ios:cellular perm:ios:applications perm:ios:wifi perm:ios:ring perm:ios:location perm:ios:notification perm:ios:airplay perm:ios:caldav perm:ios:cal-subscription perm:ios:passcode-policy perm:ios:webclip perm:ios:vpn perm:ios:per-app-vpn perm:ios:app-to-per-app-vpn perm:ios:app-lock perm:ios:clear-passcode perm:ios:remove-profile perm:ios:get-restrictions perm:ios:wipe-data perm:admin perm:android:enroll perm:android:wipe perm:android:ring perm:android:lock-devices perm:android:configure-vpn perm:android:configure-wifi perm:android:enroll perm:android:uninstall-application perm:android:manage-configuration perm:android:location perm:android:install-application perm:android:mute perm:android:change-lock-code perm:android:blacklist-applications perm:android:set-password-policy perm:android:encrypt-storage perm:android:clear-password perm:android:enterprise-wipe perm:android:info perm:android:view-configuration perm:android:upgrade-firmware perm:android:set-webclip perm:android:send-notification perm:android:disenroll perm:android:update-application perm:android:unlock-devices perm:android:control-camera perm:android:reboot perm:android:logcat" -H "Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "Content-Type: application/x-www-form-urlencoded" https://gateway.api.cloud.wso2.com/token

This returns response as following.

{"access_token":"xxxxxxxxxxxxxxxxxxxxxxx","refresh_token":"xxxxxxxxxxxxxxxxxxxxxx","scope":"perm:admin-groups:count perm:admin-groups:view perm:admin-users:view perm:admin:certificates:add perm:admin:certificates:delete perm:admin:certificates:details perm:admin:certificates:verify perm:admin:certificates:view perm:admin:devices:view perm:android:blacklist-applications perm:android:change-lock-code perm:android:clear-password perm:android:configure-vpn perm:android:configure-wifi perm:android:control-camera perm:android:disenroll perm:android:encrypt-storage perm:android:enroll perm:android:enterprise-wipe perm:android:info perm:android:install-application perm:android:location perm:android:lock-devices perm:android:logcat perm:android:manage-configuration perm:android:mute perm:android:reboot perm:android:ring perm:android:send-notification perm:android:set-password-policy perm:android:set-webclip perm:android:uninstall-application perm:android:unlock-devices perm:android:update-application perm:android:upgrade-firmware perm:android:view-configuration perm:android:wipe perm:applications:install perm:applications:uninstall perm:device-types:features perm:device-types:types perm:devices:applications perm:devices:compliance-data perm:devices:delete perm:devices:details perm:devices:effective-policy perm:devices:features perm:devices:operations perm:devices:search perm:devices:update perm:devices:view perm:get-activity perm:groups:add perm:groups:assign perm:groups:count perm:groups:device perm:groups:devices perm:groups:devices-add perm:groups:devices-count perm:groups:devices-remove perm:groups:groups perm:groups:groups-view perm:groups:remove perm:groups:roles perm:groups:share perm:groups:update perm:ios:airplay perm:ios:apn perm:ios:app-list perm:ios:app-lock perm:ios:app-to-per-app-vpn perm:ios:applications perm:ios:cal-subscription perm:ios:caldav perm:ios:cellular perm:ios:clear-passcode perm:ios:device-info perm:ios:email perm:ios:enroll perm:ios:enterprise-app perm:ios:enterprise-wipe perm:ios:get-restrictions perm:ios:ldap perm:ios:location perm:ios:lock perm:ios:notification perm:ios:passcode-policy perm:ios:per-app-vpn perm:ios:profile-list perm:ios:remove-application perm:ios:remove-profile perm:ios:restriction perm:ios:ring perm:ios:store-application perm:ios:view-device perm:ios:vpn perm:ios:webclip perm:ios:wifi perm:ios:wipe-data perm:manage-configuration perm:notifications:mark-checked perm:notifications:view perm:policies:activate perm:policies:changes perm:policies:deactivate perm:policies:get-details perm:policies:get-policy-details perm:policies:manage perm:policies:priorities perm:policies:remove perm:policies:update perm:roles:add perm:roles:add-users perm:roles:create-combined-role perm:roles:delete perm:roles:details perm:roles:permissions perm:roles:update perm:roles:view perm:users:add perm:users:count perm:users:credentials perm:users:delete perm:users:details perm:users:is-exist perm:users:roles perm:users:search perm:users:send-invitation perm:users:update perm:users:user-details perm:view-configuration","token_type":"Bearer","expires_in":3600}

In this response, user will receive “access_token” and “refresh_token”. Access token is valid for one hour.

Please note : You can find steps to get these scopes from https://docs.wso2.com/display/DeviceCloud/Getting+the+Scope+Details+of+an+API

Step 3:

Access token will be expired in one hour. After expiration user can use refresh token to get new access token.

curl -k -d "grant_type=refresh_token&refresh_token=[refresh token received before]&scope=PRODUCTION" -H "Authorization: Basic [Base64encode(client_id:client_secret)]" -H "Content-Type: application/x-www-form-urlencoded" https://gateway.api.cloud.wso2.com/token

Please refer the following sample request.

Step 3 - Example :


curl -k -d "grant_type=refresh_token&refresh_token=77xxxxxxxxxxxxxxxxxxxxxxxxxxxx8b&scope=PRODUCTION" -H "Authorization: Basic Q2xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBh" -H "Content-Type: application/x-www-form-urlencoded" https://gateway.api.cloud.wso2.com/token

This will return following response.

{"access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","refresh_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","scope":"perm:admin-groups:count perm:admin-groups:view perm:admin-users:view perm:admin:certificates:add perm:admin:certificates:delete perm:admin:certificates:details perm:admin:certificates:verify perm:admin:certificates:view perm:admin:devices:view perm:android:blacklist-applications perm:android:change-lock-code perm:android:clear-password perm:android:configure-vpn perm:android:configure-wifi perm:android:control-camera perm:android:disenroll perm:android:encrypt-storage perm:android:enroll perm:android:enterprise-wipe perm:android:info perm:android:install-application perm:android:location perm:android:lock-devices perm:android:logcat perm:android:manage-configuration perm:android:mute perm:android:reboot perm:android:ring perm:android:send-notification perm:android:set-password-policy perm:android:set-webclip perm:android:uninstall-application perm:android:unlock-devices perm:android:update-application perm:android:upgrade-firmware perm:android:view-configuration perm:android:wipe perm:applications:install perm:applications:uninstall perm:device-types:features perm:device-types:types perm:devices:applications perm:devices:compliance-data perm:devices:delete perm:devices:details perm:devices:effective-policy perm:devices:features perm:devices:operations perm:devices:search perm:devices:update perm:devices:view perm:get-activity perm:groups:add perm:groups:assign perm:groups:count perm:groups:device perm:groups:devices perm:groups:devices-add perm:groups:devices-count perm:groups:devices-remove perm:groups:groups perm:groups:groups-view perm:groups:remove perm:groups:roles perm:groups:share perm:groups:update perm:ios:airplay perm:ios:apn perm:ios:app-list perm:ios:app-lock perm:ios:app-to-per-app-vpn perm:ios:applications perm:ios:cal-subscription perm:ios:caldav perm:ios:cellular perm:ios:clear-passcode perm:ios:device-info perm:ios:email perm:ios:enroll perm:ios:enterprise-app perm:ios:enterprise-wipe perm:ios:get-restrictions perm:ios:ldap perm:ios:location perm:ios:lock perm:ios:notification perm:ios:passcode-policy perm:ios:per-app-vpn perm:ios:profile-list perm:ios:remove-application perm:ios:remove-profile perm:ios:restriction perm:ios:ring perm:ios:store-application perm:ios:view-device perm:ios:vpn perm:ios:webclip perm:ios:wifi perm:ios:wipe-data perm:manage-configuration perm:notifications:mark-checked perm:notifications:view perm:policies:activate perm:policies:changes perm:policies:deactivate perm:policies:get-details perm:policies:get-policy-details perm:policies:manage perm:policies:priorities perm:policies:remove perm:policies:update perm:roles:add perm:roles:add-users perm:roles:create-combined-role perm:roles:delete perm:roles:details perm:roles:permissions perm:roles:update perm:roles:view perm:users:add perm:users:count perm:users:credentials perm:users:delete perm:users:details perm:users:is-exist perm:users:roles perm:users:search perm:users:send-invitation perm:users:update perm:users:user-details perm:view-configuration","token_type":"Bearer","expires_in":3600}


One refresh token can used once. User cannot use the same refresh token twice to generate the access token. If that calls breaks due to any reason, user has to use 2 method (password grant type) to generate the access token.



How to invoke APIs?

Invoking APIs will be straightforward after getting the access token from above methods. Please refer following sample api calls. You can find more informations of the available APIs as swagger contracts.

Retrieving device list


curl -v -k -X GET -H 'authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxx' ‘https://gateway.api.cloud.wso2.com/api/device-mgt/v1.0/devices/1.0.0’

Send Message To Android Devices


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxx' -d '{  "deviceIDs": ["799427f59da282b8","33333"], "operation": {"messageText": "Test Message","messageTitle": "Test Title"}}' 'https://gateway.api.cloud.wso2.com/api/device-mgt/android/v1.0/admin/devices/send-notification'

Ring the devices

curl -v -k -X POST -H 'Authorization: Bearer 2c3e41a8-db85-3d67-a7b6-63517448af8c' -d '["799427f59da282b8", "5312k14212l12" ]' 'https://gateway.api.cloud.wso2.com/api/device-mgt/android/v1.0/admin/devices/ring' -H 'Content-Type: application/json'

Summary

This blog walks you through how to use Device Cloud APIs from WSO2’s Cloud. These APIs can be used to build your own dashboard or agent for devices.

Comments

Post a Comment

Popular posts from this blog

WSO2 ESB Removing full soap header using enrich mediator.

WSO2 ESB supports many mediators, and we can use them to achieve most of our use cases. The following message template illustrates the structure of a SOAP Envelope: <soap:Envelope   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">   <soap:Header> <!-- optional -->     <!-- header blocks go here... -->   </soap:Header>   <soap:Body>     <!-- payload or Fault element goes here... -->   </soap:Body> </soap:Envelope> Even though soap header is optional, you might receive the soap envelop with soap headers. And you might need to remove the soap header element including <soap:Header></soap:Header> element. You can achieve this by using enrich mediator and payload factory mediator. We first extract the body from the soap envelop and assign it to a property using enrich mediator. Then we create an empty soap envelop using payload factory. At last enrich mediator is again used to put the soap b
Read more

Running a Standalone WSO2 IoT Server.

WSO2 IoT Server  can be run on single instance with simple configurations.  WSO2 IoT server  consists of 3 major services. IoT Core — This service includes all the major device management capabilities such as operation, policy management etc. It also includes the security and API management capabilities. Analytics — This service includes components for data gathering and analysis in both real-time and batch. It also includes the capability to do machine learning as well complex event processing and fraud detection. Broker — This service acts as the message exchanger between server and devices. By default, WSO2 IoT server uses OAuth as the security mechanism. When a user login into the devicemgt user interface, it uses the OAuth token to validate the user in the underlying infrastructure. It supports few OAuth grant types and by default devicemgt application user the JWT token grant type. And by default WSO2 IoT Server runs as with the hostname as localhost. If you do not
Read more