Assign and push profiles

The Knox Configure v2 APIs provide functionalities to assign profiles to devices and push profile updates. This tutorial shows you how to assign a profile to devices, unassign a profile from devices, and push profile updates to devices.

Prerequisites

Ensure that you have the necessary permissions to assign and manage profiles and obtain an authentication token. For more information, see Get started. Include your access token in the Authorization: Bearer <access_token> header of every request. Access tokens expire after 30 minutes.

Assign a profile to devices

1. To assign a profile to a list of devices, make a POST request to the /kc/v2/profiles/{profileId}/bulkAssign endpoint. This operation requires the kc.profile:assign scope.

2. In the request, specify the profileId as a path parameter. In the request body, you can use the following parameters:

   • licenseKey — The license to be used for the assignment. This is a required parameter.
   • deviceIds — The IMEIs or serial numbers of devices to assign the profile to. This is a required parameter.

For example, the following request body assigns the profile with ID 1129471783 to the devices with the specified IMEIs and serial numbers, using the license key KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS:

POST /kc/v2/profiles/1129471783/bulkAssign

{
  "licenseKey": "KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS",
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ]
}

You can adjust the license key and device IDs based on the devices you want to assign the profile to. For detailed response schema, see POST /kc/v2/profiles/{profileId}/bulkAssign.

Unassign a profile from devices

1. To unassign a profile from a list of devices, make a POST request to the /kc/v2/profiles/bulkUnassign endpoint. This operation requires the kc.profile:assign scope.

2. In the request body, you can use the following parameter:

   • deviceIds — The IMEIs or serial numbers of devices to unassign the profile from. This is a required parameter.

For example, the following request body unassigns the profile from the devices with the specified IMEIs and serial numbers:

{
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ]
}

You can adjust the device IDs based on the devices you want to unassign the profile from. For detailed response schema, see POST /kc/v2/profiles/bulkUnassign.

Push profile updates

1. To push a profile update to one or more devices, make a POST request to the /kc/v2/profiles/{profileId}/bulkPush endpoint. This operation requires the kc.profile:manage scope.

2. In the request, specify the profileId as a path parameter. In the request body, you can use the following parameters:

   • profilePushType — The type of profile push. Possible values are ProfilePush and ProfileDeltaPush. ProfilePush updates only the changed items in the profile, and ProfileDeltaPush performs a full profile update including all items. This is a required parameter.
   • deviceIds — The IMEIs or serial numbers of devices to push the profile update to. If not passed, all devices currently assigned to the profile are updated.
   • noUserConsent — Specifies whether to request consent from the device user. Set to true to skip the consent request. The default value is false.
   • customPushMessageId — The identifier of the custom push message to include with the update.

For example, the following request body pushes a ProfilePush update to the devices with the specified IMEIs and serial numbers, without requesting user consent:

POST /kc/v2/profiles/1129471783/bulkPush

{
  "profilePushType": "ProfilePush",
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ],
  "noUserConsent": false
}

You can adjust the push type, device IDs, and consent settings based on your update requirements. A successful request returns 202 Accepted, which means the push request was accepted for processing. It does not mean that the update has been applied to the devices. For detailed response schema, see POST /kc/v2/profiles/{profileId}/bulkPush.

Ensure that you check the code and message in the response for any errors and handle them appropriately for your app. See Error codes for the full list of Knox Configure error codes. For detailed specification, see Knox Configure API reference.