Page History

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.

Table of Contents

maxLevel	3
minLevel	3

Tip

title	Before you begin

Start the core profile of WSO2 IoT Server.

Code Block
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.

Encode the client credentials as follows:

Localtab Group

Localtab

active	true
title	Linux/Mac

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block
echo -n <USERNAME>:<PASSWORD> \| base64

Example:

Code Block
echo -n admin:admin \| base64

The response:

Code Block
YWRtaW46YWRtaW4=

Localtab

title	Windows

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

Example:

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

The response:

Code Block
YWRtaW46YWRtaW4=

Generate the Client ID and the Secret ID.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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"]}'

Info

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:

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

Localtab

title	Example:

Panel

Code Block

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:

Code Block
{"client_secret":"nboXPDTm9S1cK1yPbhAvJenbbzsa","client_id":"Ad9iV9VJ9EwyujpmLVzCi59rX8Aa"}

Encode the client credentials as follows:

Localtab Group

Localtab

active	true
title	Linux/Mac

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block
echo -n <CLIENT_ID>:<CLIENT_SECRET> \| base64

Example:

Code Block
echo -n f8fc0aI14DPrQ_DwkpSau1LGdwAa:p8g_rFXtbPjl5pGMJe4bNd5fwSEa \| base64

The response:

Code Block
cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh

Localtab

title	Windows

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

Example:

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

The response:

Code Block
cDhnX3JGWHRiUGpsNXBHTUplNGJOZDVmd1NFYTpmOGZjMGFJMTREUHJRX0R3a3BTYXUxTEdkd0Fh

Generate the access token using the following command:

Localtab Group

Localtab

title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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

Info

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.

For more information on all the device management API scopes, see Device Management API Scopes.
For more information on how to know the API scope for the API you need to invoke, see Getting the Scope Details of an API.

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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.

Code Block

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:

Code Block

{   "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
}

Note
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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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:

Code Block

{"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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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

Expand

title	Click here for more information on the payload that was passed to create a policy.

Code Block

{
  "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 value	Description
`profile`	Provide the policy profile details.
`profileName`	The 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.
`profileFeaturesList`	Lists 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.
`policyName`	The name of the policy you are adding. The property to identify the policies added in a profile of policies.
`roles`	Define the roles the policy needs to be applied on. The policy will be applied to the respective user role's devices.
`devices`	Define 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.
`updated`	Indicates if the policy was updated. When creating a policy you can assign the value as `false`.
`description`	Provide 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.

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

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

Code Block

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:

Code Block

*   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"}

Info

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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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

Expand

title	Click here for more information on the payload that was passed to enroll an Android device.

Example:

Code Block

{    "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\"}]"
      }
   ]
}

Property Description Data 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.

Note
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

name The 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.

Localtab

title	Example:

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

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

Code Block

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:

Code Block

*   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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

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

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

The response:

Info
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.

Code Block

*   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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

Info

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.

Expand

title	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.

Code Block
"deviceIdentifier":"867115026844132"

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

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

Code Block
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:

Code Block

* 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.

Localtab Group

Localtab

active	true
title	cURL command

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

Code Block

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'

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

Localtab

title	Example

Panel

borderColor	#11375B
bgColor	#ffffff
borderWidth	2

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

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

Code Block

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:

Code Block

*   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"}]}

Info

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.

Note
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.

Versions Compared

Old Version 35

New Version Current

Key

Obtaining the access token

Generating a new access token from the refresh token

Creating an active policy

Enrolling an Android device

Getting the details of the devices registered with WSO2 IoT Server

Getting the details of a specific device

Carrying out an operation on a device

What's next?