This documentation is for WSO2 IoT Server 3.1.0. View the documentation for the latest release.
Getting Started with APIs - IoT Server 3.1.0 - WSO2 Documentation
                                                                                                                                                                                                                                                                                                                                                                                                                                                   
||
Skip to end of metadata
Go to start of metadata

You can enroll a device, carry out operations on a device, group devices, apply policies on devices, and much more with WSO2 IoT Server's User Interface (UI). You can do the same tasks using WSO2 IoT Server's APIs. All the device management capabilities are offered as OAuth2 protected REST APIs. Therefore, you can create your own custom scenario using these APIs.

In this tutorial, you will create a policy, enroll an Android device, try out a device operation, and get the details of the device user via REST APIs.

Before you begin

Start the core profile of WSO2 IoT Server.

cd <IOTS_HOME>/bin
./iot-server.sh

Let's  get started!

Obtaining the access token

You can obtain an access token by providing the resource owner's username and password as an authorization grant. It requires the base64 encoded string of the consumer-key:consumer-secret combination. Let's take a look at how it's done.

  1. Encode the client credentials as follows:

    echo -n <USERNAME>:<PASSWORD> | base64

    Example:

    echo -n admin:admin | base64

    The response:

    YWRtaW46YWRtaW4=
    powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<USERNAME>:<PASSWORD>\"))

    Example:

    powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"admin:admin\"))

    The response:

    YWRtaW46YWRtaW4=
  2. Generate the Client ID and the Secret ID.

    curl -k -X POST https://<IOTS_HOST>:8243/api-application-registration/register -H 'authorization: Basic <BASE 64 ENCODED USERNAME:PASSWORD>' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_management"]}'
    • The base 64 encoded USERNAME :PASSWORD must be the username and password that you use to sign in to WSO2 IoT Server. Else, you will not be able to get the client_id and client_secret as the response.
    • The APIs that fall under different categories are grouped using tags. You can subscribe to an API group by defining the tag in the cURL command.
      For example, the device_management tag is used to group all the device management APIs including those that belong to the device type APIs.
      To know about the available tags and the APIs grouped under each tag, navigate to the API Cloud Store, and click on the available tags in the left side panel.

    The response:

    {"client_secret":"xxxxxxxxxxxxxxxxxxxx","client_id":"xxxxxxxxxxxxxxxxxxxx"}
    curl -k -X POST https://localhost:8243/api-application-registration/register -H 'authorization: Basic YWRtaW46YWRtaW4=' -H 'content-type: application/json' -d '{ "applicationName":"appName", "tags":["device_management"]}'

    The response:

    {"client_secret":"nboXPDTm9S1cK1yPbhAvJenbbzsa","client_id":"Ad9iV9VJ9EwyujpmLVzCi59rX8Aa"}
  3. Encode the client credentials as follows:

    echo -n <CLIENT_ID>:<CLIENT_SECRET> | base64

    Example:

    echo -n f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa | base64

    The response:

    cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
    powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<CLIENT_ID>:<CLIENT_SECRET>\"))

    Example:

    powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa\"))

    The response:

    cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh
  4. Generate the access token using the following command:

    curl -v -k -d "grant_type=password&username=<USERNAME>&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: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 <BASE 64 ENCODEd CLIENT_ID:CLIENT_SECRET>" -H "Content-Type: application/x-www-form-urlencoded" https://<IOTS_HOST>:8243/token

    The permission to invoke the APIs are assigned via the scope defined in each API. You can define all the scopes to generate an access token that can invoke all the APIs or you can generate an access token that only has the required scope to invoke a specific API.

    Generate the access token for the user having the username admin and password admin, and using the default WSO2 IoT Server host, which is localhost. In this example, we are generating an access token that has access to all the device management scopes.

    curl -v -k -d "grant_type=password&username=admin&password=admin&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: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 QWQ5aVY5Vko5RXd5dWpwbUxWekNpNTlyWDhBYTpuYm9YUERUbTlTMWNLMXlQYmhBdkplbmJienNh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

    The response:

    {   "access_token":"168v5699-5678-rt61-1534-4a169v5u88e0",
       "refresh_token":"3trtg45-64t5-1693-gr56-6th5356r4tr5",
       "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":3880
    }

    The access token you generated expires in an hour. After it expires you can generate a new access token using the refresh token as shown below.


Generating a new access token from the refresh token

The access token expires in an hour. Let's look at how to use the refresh token to generate a new access token using the cURL command given below.

curl -k -d "grant_type=refresh_token&refresh_token=<THE REFRESH TOKEN>&scope=PRODUCTION" -H "Authorization: Basic <BASE 64 ENCODED CLIENT_ID:CLIENT_SECRET>" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token
curl -k -d "grant_type=refresh_token&refresh_token=3trtg45-64t5-1693-gr56-6th5356r4tr5&scope=PRODUCTION" -H "Authorization: Basic cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

The response:


{"access_token":"237bfc64-9567-3edf-9ad6-3795d37fa368","refresh_token":"62e597b3-0960-39c0-894f-7056fcdf2dc6","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: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}

Creating an active policy

In this section let's look at creating an active policy using the cURL command given below. The active policies are pushed to devices that register with WSO2 IoT Server after creating the policy. 


curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" -d '{"profile":{"profileName":"string","deviceType":"string","profileFeaturesList":[{"featureCode":"string","deviceType":"string","content":"{}"}]},"policyName":"string","roles":["string"],"devices":[{"id":"string","type":"string"}],"ownershipType":"string","active":boolean,"updated":boolean,"description":"string","compliance":"string","tenantId":short,"profileId":integer}' -k -v https://<IOTS_HOST>:8243/api/device-mgt/v1.0/policies
 Click here for more information on the payload that was passed to create a policy.
{
  "profile": {
    "profileName": "Passcode Policy",
    "deviceType": "android",
    "profileFeaturesList": [
      {
        "featureCode": "PASSCODE_POLICY",
        "deviceType": "android",
        "content": "{\"allowSimple\":true,\"requireAlphanumeric\":true,\"maxFailedAttempts\":\"3\"}"
      }
    ]
  },
  "policyName": "Passcode Policy",
  "roles": [
    "ANY"
  ],
  "devices": [
    
  ],
  "onwershipType": "COPE""active": true,
  "updated": false,
  "description": "If the worng password is entered more than 3 times the device is locked.",
  "compliance": "enforce"
}
Property valueDescription
profileProvide the policy profile details.
profileNameThe name of the policy. You can create a number of policies at once. A group of policies is referred to as a profile in WSO2 IoT Server.
deviceType

Defines the device type or mobile platform the policy needs to be published after its created.

profileFeaturesListLists the features that belong to the profile.
featureCode

Provide the code that defines the policy you wish to add.

Example: PASSCODE_POLICY, CAMERA and ENCRYPT_STORAGE.

content

The list of parameters that define the policy.

policyNameThe name of the policy you are adding. The property to identify the policies added in a profile of policies.
rolesDefine the roles the policy needs to be applied on. The policy will be applied to the respective user role's devices.
devicesDefine the ID of the devices. This is not a mandatory field.
active

If the value is true, the policy is in the active state. The active policies will be applied to the devices that register with WSO2 IoT Server based on the Policy enforcement criteria.

If the value is false, the policy is in the inactive state. Such policies will not be considered when applying policies to the device that registers with WSO2 IoT Server.

updatedIndicates if the policy was updated. When creating a policy you can assign the value as false.
descriptionProvide a description on what the policy is based on.
compliance

Define the non-compliance rules. WSO2 IoT Server provides the following non-compliance rules:

  • Enforce - Forcefully enforce the policies on the devices.
  • Warning - If the device does not adhere to the given policies a warning message will be sent.
  • Monitor - If the device does not adhere to the given policies the server is notified of the violation unknown to the user and the administrator can take the necessary actions with regard to the reported.
ownershipType

Define the ownership type using the values given below:

  • ANY - The policy will be applied on the BYOD and COPE device types.
  • BYOD (Bring Your Own Device) - The policy will only be applied on the BYOD device type.
  • COPE (Corporate-Owned, Personally-Enabled) - The policy will only be applied on the COPE device type.

Create the passcode policy using the default WSO2 IoT Server host, which is localhost.

Make sure to use your access token when you are running the sample given below. Else, you will run into errors.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer 2de91df4-9396-3710-926f-a4bf329fc5cb" -d '{"profile":{"profileName":"Passcode Policy","deviceType":"android","profileFeaturesList":[{"featureCode":"PASSCODE_POLICY","deviceType":"android","content":"{\"allowSimple\":true,\"requireAlphanumeric\":true,\"maxFailedAttempts\":\"3\"}"}]},"policyName":"Passcode Policy","roles":["ANY"],"devices":[],"onwershipType":"COPE","active":true,"updated":false,"description":"If the worng password is entered more than 3 times the device is locked.","compliance":"enforce"}' -k -v https://localhost:8243/api/device-mgt/v1.0/policies

The response:

*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8243 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> POST /api/device-mgt/v1.0/policies HTTP/1.1
> Host: localhost:8243
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer 2de91df4-9396-3710-926f-a4bf329fc5cb
> Content-Length: 656
> 
* upload completely sent off: 656 out of 656 bytes
< HTTP/1.1 201 Created
< X-Frame-Options: DENY
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Location: https://localhost:9443/api/device-mgt/v1.0/policies/5
< Date: Tue, 13 Jun 2017 10:08:30 GMT
< Transfer-Encoding: chunked
{"profile":{"profileName":"Passcode Policy","deviceType":"android","profileFeaturesList":[{"featureCode":"PASSCODE_POLICY","deviceType":"android","content":"{\"allowSimple\":true,\"requireAlphanumeric\":true,\"maxFailedAttempts\":\"3\"}"}]},"policyName":"Passcode Policy","roles":["ANY"],"devices":[],"onwershipType":"COPE""active":true,"updated":false,"description":"If the worng password is entered more than 3 times the device is locked.","compliance":"enforce"}

Policies in the active state are applied to new devices that register with WSO2 IoT Server. In a situation where you need to make changes to existing policies (removing, activating, deactivating and updating) or add new policies, the existing devices will not receive these changes immediately. Once all the required changes are made you need to apply the changes to push the policy changes to the existing devices. For more information on working with policies, see Policy Management.



Enrolling an Android device

In this section let's look at how you can enroll an Android device using the cURL command given below.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" -d '{"name":"string","description":"string","deviceIdentifier":"string","enrolmentInfo":{"id":0,"dateOfEnrolment":0,"dateOfLastUpdate":0,"ownership":"BYOD","status":"CREATED","owner":"string"},"features":[{"id":0,"code":"string","name":"string","description":"string","deviceType":"string","metadataEntries":[{"id":0,"value":{}}]}],"properties":[{"name":"string","value":"string"}],"advanceInfo":{"deviceModel":"string","vendor":"string","osVersion":"string","osBuildDate":"string","batteryLevel":0,"internalTotalMemory":0,"internalAvailableMemory":0,"externalTotalMemory":0,"externalAvailableMemory":0,"operator":"string","connectionType":"string","mobileSignalStrength":0,"ssid":"string","cpuUsage":0,"totalRAMMemory":0,"availableRAMMemory":0,"pluggedIn":false,"updatedTime":"2017-06-13T08:46:25.330Z","location":{"deviceId":0,"deviceIdentifier":{"id":"string","type":"string"},"latitude":0,"longitude":0,"street1":"string","street2":"string","city":"string","state":"string","zip":"string","country":"string","updatedTime":"2017-06-13T08:46:25.330Z"},"deviceDetailsMap":{},"imei":"string","imsi":"string"},"applications":[{"id":0,"platform":"string","category":"string","name":"string","locationUrl":"string","imageUrl":"string","version":"string","type":"string","appProperties":{},"applicationIdentifier":"string","memoryUsage":0,"active":false}]}' -k -v https://<IOTS_HOST>t:8243/api/device-mgt/android/v1.0/devices
 Click here for more information on the payload that was passed to enroll an Android device.

Example:

{    "description":"hwRIO-L01",
   "deviceIdentifier":"867115026844132",
   "enrolmentInfo":{ 
      "ownership":"BYOD",
      "owner":"admin"
   },
   "name":"hwRIO-L01",
   "properties":[ 
      { 
         "name":"IMEI",
         "value":"867115026844132"
      },
      { 
         "name":"IMSI",
         "value":"413027001101134"
      },
      { 
         "name":"DEVICE_MODEL",
         "value":"HUAWEI RIO-L01"
      },
      { 
         "name":"VENDOR",
         "value":"HUAWEI"
      },
      { 
         "name":"OS_VERSION",
         "value":"5.1"
      },
      { 
         "name":"DEVICE_NAME",
         "value":"hwRIO-L01"
      },
      { 
         "name":"BATTERY_LEVEL",
         "value":"77"
      },
      { 
         "name":"LATITUDE",
         "value":"6.9302368"
      },
      { 
         "name":"LONGITUDE",
         "value":"79.8617277"
      },
      { 
         "name":"INTERNAL_TOTAL_MEMORY",
         "value":"24.74"
      },
      { 
         "name":"INTERNAL_AVAILABLE_MEMORY",
         "value":"18.4"
      },
      { 
         "name":"EXTERNAL_TOTAL_MEMORY",
         "value":"0.0"
      },
      { 
         "name":"EXTERNAL_AVAILABLE_MEMORY",
         "value":"0.0"
      },
      { 
         "name":"OPERATOR",
         "value":"Dialog"
      },
      { 
         "name":"DEVICE_INFO",
         "value":"[{\"name\":\"IMEI\",\"value\":\"867115026844132\"},{\"name\":\"IMSI\",\"value\":\"413027001101134\"},{\"name\":\"DEVICE_MODEL\",\"value\":\"HUAWEI RIO-L01\"},{\"name\":\"VENDOR\",\"value\":\"HUAWEI\"},{\"name\":\"OS_VERSION\",\"value\":\"5.1\"},{\"name\":\"DEVICE_NAME\",\"value\":\"hwRIO-L01\"},{\"name\":\"BATTERY_LEVEL\",\"value\":\"77\"},{\"name\":\"LATITUDE\",\"value\":\"6.9302368\"},{\"name\":\"LONGITUDE\",\"value\":\"79.8617277\"},{\"name\":\"INTERNAL_TOTAL_MEMORY\",\"value\":\"24.74\"},{\"name\":\"INTERNAL_AVAILABLE_MEMORY\",\"value\":\"18.4\"},{\"name\":\"EXTERNAL_TOTAL_MEMORY\",\"value\":\"0.0\"},{\"name\":\"EXTERNAL_AVAILABLE_MEMORY\",\"value\":\"0.0\"},{\"name\":\"OPERATOR\",\"value\":\"Dialog\"}]"
      }
   ]
}
PropertyDescriptionData Type
description
Additional information on the device.String
deviceIdentifier

This is a 64-bit number (as a hex string) that is randomly generated when the user first sets up the device and should remain constant for the lifetime of the user's device. The value may change if a factory reset is performed on the device.

When a device has multiple users (available on certain devices running Android 4.2 or higher), each user appears as a completely separate device; therefore, the deviceIdentifier value is unique to each user.

String
enrolmentInfo
This defines the device registration related information. It is mandatory to define this information.
owner The device owner's name.String
ownership

Defines the ownership details. The ownership type can be any of the following values.

  • BYOD - Bring your own device (BYOD).
  • COPE - Corporate owned personally enabled (COPE).
String
nameThe device name that can be set on the device by the device user.String
properties

Defines details that correspond to the device. Defining properties are optional.

  • IMEI - The International Mobile Station Equipment Identity (IMEI) is a number, usually unique, which is used to identify a device.
  • IMSI - The International Mobile Subscriber Identity (IMSI) is used to identify the user of a cellular network and is a unique identification associated with all cellular networks.
  • DEVICE_MODEL - The model of the Android device.
  • VENDOR - The name of the Android device vendor.
  • OS_VERSION - The version of the Android device operating system.
  • DEVICE_NAME - The name defined for the device.
  • BATTERY_LEVEL - The current level of the Android device battery.
  • LATITUDE - The latitude of the Android device.
  • LONGITUDE - The longitude of the Android device.
  • INTERNAL_TOTAL_MEMORY - The total capacity of the internal memory availablein the Android device.
  • INTERNAL_AVAILABLE_MEMORY - The remaining capacity of the internal memory availablein the Android device.
  • EXTERNAL_TOTAL_MEMORY - The total capacity of the external memory availablein the Android device.
  • EXTERNAL_AVAILABLE_MEMORY - The remaining capacity of the external memory availablein the Android device.
  • OPERATOR - The name of the cellular network operator used with the Android device.
  • DEVICE_INFO - General information with regard to the device.
  • GCM_TOKEN - The Android Platform is configured to communicate via Local Polling. However, the Google Cloud Messaging service (GCM) token needs to be passed when the push notification service is used with the Android platform.

Enroll an Android device using the default WSO2 IoT Server host, which is localhost.

Make sure to use your access token when you are running the sample given below. Else, you will run into errors.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer 168v5699-5678-rt61-1534-4a169v5u88e0" -d '{"description":"hwRIO-L01","deviceIdentifier":"867115026844132","enrolmentInfo":{"ownership":"BYOD","owner":"admin"},"name":"hwRIO-L01","properties":[{"name":"IMEI","value":"867115026844132"},{"name":"IMSI","value":"413027001101134"},{"name":"DEVICE_MODEL","value":"HUAWEI RIO-L01"},{"name":"VENDOR","value":"HUAWEI"},{"name":"OS_VERSION","value":"5.1"},{"name":"DEVICE_NAME","value":"hwRIO-L01"},{"name":"BATTERY_LEVEL","value":"77"},{"name":"LATITUDE","value":"6.9302368"},{"name":"LONGITUDE","value":"79.8617277"},{"name":"INTERNAL_TOTAL_MEMORY","value":"24.74"},{"name":"INTERNAL_AVAILABLE_MEMORY","value":"18.4"},{"name":"EXTERNAL_TOTAL_MEMORY","value":"0.0"},{"name":"EXTERNAL_AVAILABLE_MEMORY","value":"0.0"},{"name":"OPERATOR","value":"Dialog"},{"name":"DEVICE_INFO","value":"[{\"name\":\"IMEI\",\"value\":\"867115026844132\"},{\"name\":\"IMSI\",\"value\":\"413027001101134\"},{\"name\":\"DEVICE_MODEL\",\"value\":\"HUAWEI RIO-L01\"},{\"name\":\"VENDOR\",\"value\":\"HUAWEI\"},{\"name\":\"OS_VERSION\",\"value\":\"5.1\"},{\"name\":\"DEVICE_NAME\",\"value\":\"hwRIO-L01\"},{\"name\":\"BATTERY_LEVEL\",\"value\":\"77\"},{\"name\":\"LATITUDE\",\"value\":\"6.9302368\"},{\"name\":\"LONGITUDE\",\"value\":\"79.8617277\"},{\"name\":\"INTERNAL_TOTAL_MEMORY\",\"value\":\"24.74\"},{\"name\":\"INTERNAL_AVAILABLE_MEMORY\",\"value\":\"18.4\"},{\"name\":\"EXTERNAL_TOTAL_MEMORY\",\"value\":\"0.0\"},{\"name\":\"EXTERNAL_AVAILABLE_MEMORY\",\"value\":\"0.0\"},{\"name\":\"OPERATOR\",\"value\":\"Dialog\"}]"}]}' -k -v https://localhost:8243/api/device-mgt/android/v1.0/devices

The response:

*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8243 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> POST /api/device-mgt/android/v1.0/devices HTTP/1.1
> Host: localhost:8243
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer 42cd554f-b87f-303f-889a-c6f9964e816b
> Content-Length: 1504
> Expect: 100-continue
> 
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Date: Thu, 15 Jun 2017 08:28:37 GMT
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
{"responseCode":"OK","responseMessage":"Android device, which carries the id \u0027867115026844132\u0027 has successfully been enrolled"}Shavindris-MacBook-Air:bin shavindridissanayake$ 

Getting the details of the devices registered with WSO2 IoT Server

In this section let's look at getting the details of all the devices registered with WSO2 IoT Server via the cURL command given below.

curl -v -k -X GET -H 'authorization: Bearer <ACCESS TOKEN>' 'https://<IOTS_HOST>:8243/api/device-mgt/v1.0/devices'

Get the details of all the registered devices using the default WSO2 IoT Server host, which is localhost.

Make sure to use your access token when you are running the sample given below. Else, you will run into errors.

curl -v -k -X GET -H 'authorization: Bearer 237bfc64-9567-3edf-9ad6-3795d37fa368' 'https://localhost:8243/api/device-mgt/v1.0/devices'

The response:

When running the sample command, there was only one device enrolled with WSO2 IoT Server. Therefore, the details of that device are shown as the response. If you have many devices registered with WSO2 IoT Server, the details of all the registered devices are returned.

*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8243 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> GET /api/device-mgt/v1.0/devices HTTP/1.1
> Host: localhost:8243
> User-Agent: curl/7.43.0
> Accept: */*
> authorization: Bearer 237bfc64-9567-3edf-9ad6-3795d37fa368
> 
< HTTP/1.1 200 OK
< X-Frame-Options: DENY
< Cache-Control: private
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< X-Content-Type-Options: nosniff
< Expires: Thu, 01 Jan 1970 05:30:00 IST
< X-XSS-Protection: 1; mode=block
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Date: Wed, 14 Jun 2017 11:30:17 GMT
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
{"devices":[{"id":1,"name":"hwRIO-L01","type":"android","description":"hwRIO-L01","deviceIdentifier":"867115026844132","enrolmentInfo":{"id":1,"dateOfEnrolment":1497260609213,"dateOfLastUpdate":1497260609213,"ownership":"BYOD","status":"ACTIVE","owner":"admin"},"properties":[{"name":"FCM_TOKEN"},{"name":"DEVICE_INFO","value":"[{\"name\":\"IMEI\",\"value\":\"867115026844132\"},{\"name\":\"IMSI\",\"value\":\"413027001101134\"},{\"name\":\"DEVICE_MODEL\",\"value\":\"HUAWEI RIO-L01\"},{\"name\":\"VENDOR\",\"value\":\"HUAWEI\"},{\"name\":\"OS_VERSION\",\"value\":\"5.1\"},{\"name\":\"DEVICE_NAME\",\"value\":\"hwRIO-L01\"},{\"name\":\"BATTERY_LEVEL\",\"value\":\"77\"},{\"name\":\"LATITUDE\",\"value\":\"6.9302368\"},{\"name\":\"LONGITUDE\",\"value\":\"79.8617277\"},{\"name\":\"INTERNAL_TOTAL_MEMORY\",\"value\":\"24.74\"},{\"name\":\"INTERNAL_AVAILABLE_MEMORY\",\"value\":\"18.4\"},{\"name\":\"EXTERNAL_TOTAL_MEMORY\",\"value\":\"0.0\"},{\"name\":\"EXTERNAL_AVAILABLE_MEMORY\",\"value\":\"0.0\"},{\"name\":\"OPERATOR\",\"value\":\"Dialog\"}]"},{"name":"IMEI","value":"867115026844132"},{"name":"IMSI","value":"413027001101134"},{"name":"OS_VERSION","value":"5.1"},{"name":"DEVICE_MODEL","value":"HUAWEI RIO-L01"},{"name":"VENDOR","value":"HUAWEI"},{"name":"LATITUDE","value":"6.9302368"},{"name":"LONGITUDE","value":"79.8617277"},{"name":"SERIAL"},{"name":"MAC_ADDRESS"},{"name":"DEVICE_NAME","value":"hwRIO-L01"},{"name":"OS_BUILD_DATE"}],"applications":[]}],"count":1}

Getting the details of a specific device

In this section, you will get the details of a specific device using the cURL command given below.

curl -v -k -X GET -H 'authorization: Bearer <ACCESS TOKEN>' 'https://<IOTS_HOST>:8243/api/device-mgt/v1.0/devices/<DEVICE_TYPE>/<DEVICE_IDENTIFIER>'
  • DEVICE_TYPE refers to the device type name, such as ios, android, windows, fire-alarm and more.
  • DEVICE_IDENTIFIER refers to the unique device ID of the device.

     Don't know the device ID?

    Run the API command to get the details of all the registered devices. Search for deviceIdentifier in the response that's returned. You will be able to find all the ID's of the devices.
    For example, in the sample response you received, the device identifier of the registered device is shown below.

    "deviceIdentifier":"867115026844132"

Get the details of the device you just enrolled using the default WSO2 IoT Server host, which is localhost.

Make sure to use your access token when you are running the sample given below. Else, you will run into errors.

curl -v -k -X GET -H 'authorization: Bearer 237bfc64-9567-3edf-9ad6-3795d37fa368' 'https://localhost:8243/api/device-mgt/v1.0/devices/android/867115026844132'

The response:

* Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8243 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> GET /api/device-mgt/v1.0/devices/android/867115026844132 HTTP/1.1
> Host: localhost:8243
> User-Agent: curl/7.43.0
> Accept: */*
> authorization: Bearer 237bfc64-9567-3edf-9ad6-3795d37fa368
> 
< HTTP/1.1 200 OK
< X-Frame-Options: DENY
< Cache-Control: private
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< X-Content-Type-Options: nosniff
< Expires: Thu, 01 Jan 1970 05:30:00 IST
< X-XSS-Protection: 1; mode=block
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Date: Wed, 14 Jun 2017 11:51:59 GMT
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
{"id":1,"name":"hwRIO-L01","type":"android","description":"hwRIO-L01","deviceIdentifier":"867115026844132","enrolmentInfo":{"id":1,"dateOfEnrolment":1497260609213,"dateOfLastUpdate":1497260609213,"ownership":"BYOD","status":"ACTIVE","owner":"admin"},"properties":[{"name":"FCM_TOKEN"},{"name":"DEVICE_INFO","value":"[{\"name\":\"IMEI\",\"value\":\"867115026844132\"},{\"name\":\"IMSI\",\"value\":\"413027001101134\"},{\"name\":\"DEVICE_MODEL\",\"value\":\"HUAWEI RIO-L01\"},{\"name\":\"VENDOR\",\"value\":\"HUAWEI\"},{\"name\":\"OS_VERSION\",\"value\":\"5.1\"},{\"name\":\"DEVICE_NAME\",\"value\":\"hwRIO-L01\"},{\"name\":\"BATTERY_LEVEL\",\"value\":\"77\"},{\"name\":\"LATITUDE\",\"value\":\"6.9302368\"},{\"name\":\"LONGITUDE\",\"value\":\"79.8617277\"},{\"name\":\"INTERNAL_TOTAL_MEMORY\",\"value\":\"24.74\"},{\"name\":\"INTERNAL_AVAILABLE_MEMORY\",\"value\":\"18.4\"},{\"name\":\"EXTERNAL_TOTAL_MEMORY\",\"value\":\"0.0\"},{\"name\":\"EXTERNAL_AVAILABLE_MEMORY\",\"value\":\"0.0\"},{\"name\":\"OPERATOR\",\"value\":\"Dialog\"}]"},{"name":"IMEI","value":"867115026844132"},{"name":"IMSI","value":"413027001101134"},{"name":"OS_VERSION","value":"5.1"},{"name":"DEVICE_MODEL","value":"HUAWEI RIO-L01"},{"name":"VENDOR","value":"HUAWEI"},{"name":"LATITUDE","value":"6.9302368"},{"name":"LONGITUDE","value":"79.8617277"},{"name":"SERIAL"},{"name":"MAC_ADDRESS"},{"name":"DEVICE_NAME","value":"hwRIO-L01"},{"name":"OS_BUILD_DATE"}],"applications":[]}

Carrying out an operation on a device

Use the following cURL command to ring your enrolled Android device.

curl -v -k -X POST -H "Content-Type: application/json" -H 'authorization: Bearer <ACCESS TOKEN>' -d '["<DEVICEIDENTIFIER OF THE ENROLLED ANDROID DEVICE>","<DEVICEIDENTIFIER OF THE ENROLLED ANDROID DEVICE>"]' 'https://<IOTS_HOST>:8243/api/device-mgt/android/v1.0/admin/devices/ring'

The device operations can be sent to multiple devices by defining the DEVICE_IDENTIFIERS using comma separated values.

Carrying out the ring operation on your device using the default WSO2 IoT Server host, which is localhost.

Make sure to use your access token when you are running the sample given below. Else, you will run into errors.

curl -v -k -X POST -H "Content-Type: application/json" -H 'authorization: Bearer aee596d0-a1ba-3706-8db6-e2dcd8641472' -d '["867115026844132"]' 'https://localhost:8243/api/device-mgt/android/v1.0/admin/devices/ring'

The response:

*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 8243 (#0)
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
* Server certificate: localhost
> POST /api/device-mgt/android/v1.0/admin/devices/ring HTTP/1.1
> Host: localhost:8243
> User-Agent: curl/7.43.0
> Accept: */*
> Content-Type: application/json
> authorization: Bearer aee596d0-a1ba-3706-8db6-e2dcd8641472
> Content-Length: 19
> 
* upload completely sent off: 19 out of 19 bytes
< HTTP/1.1 201 Created
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
< Access-Control-Allow-Headers: Content-Type
< Content-Type: application/json
< Date: Wed, 14 Jun 2017 12:23:17 GMT
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
{"activityId":"ACTIVITY_420","code":"DEVICE_RING","type":"COMMAND","createdTimeStamp":"Wed Jun 14 17:53:17 IST 2017","activityStatus":[{"deviceIdentifier":{"id":"867115026844132","type":"android"},"status":"PENDING"}]}

Initially, the operation is in the pending state as the operation is delivered to the device but the response from the device is pending. Once the operation is delivered to the device and is executed the status of the operation will change to complete.
The operation has the following statuses:

  • PENDING - The operation is not delivered to the device yet or the operation is delivered to the device but the response from the device is pending.
  • COMPLETED - The operation is delivered to the device and the server has received a response back from the device.
  • ERROR - An error has occurred while carrying out the operation.
  • IN-PROGRESS - The operation is being executed on the device but is taking to be completed. This will be shown for device operations such as upgrade firmware.

The device you enrolled using the example given above is not a real device. Therefore, the operation you sent will be in the PENDING state because the server is trying to contact the device and trigger the ring operation.

What's next?

Take a look at all the APIs on WSO2 IoT Server and try them out.

  • No labels