Manage profiles

The Knox Configure v2 APIs provide functionalities to manage configuration profiles for your devices. This tutorial focuses on how to create, retrieve, and delete profiles.

Prerequisites

Ensure that you have the necessary permissions to 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.

Create a profile

1. To create a new application profile, make a POST request to the /kc/v2/profiles endpoint. This operation requires the kc.profile:manage scope.

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

   • name — The name of the profile to be created. This is displayed during enrollment. This is a required parameter.
   • description — The description of the profile shown during enrollment.
   • profileType — The type of profile. Possible values are Setup and Dynamic. Setup profiles are applied during initial device setup, and Dynamic profiles can be updated and pushed to devices.
   • enrollmentLicenseKey — License key to be used as the default for the profile.
   • knoxVersion — Knox version of the profile to be created. Defaults to version 2.9.
   • deviceLevel — Specifies whether the profile is meant for Samsung Knox devices or other Android devices. Possible values are Knox and Other.
   • customerSupport — Contains the company and customer support details of the profile, such as company name, address, and contact information.
   • welcomeScreenConfig — Branding customization for the background and logo of the enrollment screen.
   • additionalEula — The optional end-user license agreement displayed during enrollment, updates, and special permission flows.
   • applicationIds — List of unique content IDs of the applications to be included in the profile.
   • folderConfig — Configuration for the Google Play folder, including the Google Play folder and resolution settings.
   • productInfoScreen — Product information shown on the device, including the product info name and a non-dismissible notification.
   • lockScreenHiddenWidgets — Specifies which widgets are hidden on the lock screen, such as the time, date, owner information, help text, battery information, and shortcuts widgets. All widgets are shown by default.

For example, the following request body creates a Setup profile named My profile with a description, a license key, and customer support details:

{
  "name": "My profile",
  "description": "Profile for Region-1 devices",
  "profileType": "Setup",
  "enrollmentLicenseKey": "KLM00-SSSSS-SSSSS-SSSSS-SSSSS-SSSSS",
  "knoxVersion": "2.9",
  "deviceLevel": "Knox",
  "customerSupport": {
    "companyName": "Samsung Electronics Corporation",
    "supportEmailAddress": "support@example.com",
    "supportPhoneNumber": "6048539086",
    "websiteAddress": "https://www.samsung.com"
  }
}

You can adjust the parameters in the request body based on your profile requirements. For detailed response schema, see POST /kc/v2/profiles.

Retrieve profiles

1. To retrieve a list of all profiles in your tenant, make a GET request to the /kc/v2/profiles endpoint. This operation requires the kc.profile:view scope.

2. In the request, you can make use of the following optional query parameters:

   • profileNames — List of profile names to filter by.
   • profileIds — List of profile IDs to filter by.
   • profileType — The type of profile to filter by. Possible values are Setup and Dynamic.
   • knoxVersion — Knox version of profiles to be retrieved.
   • deviceProductType — The type of device the profile is intended for. Possible values are Phone, Tablet, Wearable, and Others.
   • deviceLevel — Specifies whether the profile is meant for Samsung Knox devices or other Android devices. Possible values are Knox and Other.
   • pageNum — Page number to retrieve. The indexing count starts at 0.
   • pageSize — Number of profiles to return at once. The default value is 25.
   • sortBy — The value that results are sorted by. Possible values are updateTime and name.
   • sortOrder — The order by which results are returned. Possible values are ascending and descending.

For example, the following request retrieves all Setup profiles, sorted by name in ascending order:

GET /kc/v2/profiles?profileType=Setup&sortBy=name&sortOrder=ascending&pageNum=0&pageSize=25

You can modify the query parameters to reflect the specific profiles you want to retrieve. For detailed response schema, see GET /kc/v2/profiles.

Retrieve profile details

1. To retrieve the details of a specific profile, make a GET request to the /kc/v2/profiles/{profileId} endpoint. This operation requires the kc.profile:view scope.

2. In the request, specify the profileId as a path parameter.

For example, the following request retrieves the details of the profile with ID 1129471783:

GET /kc/v2/profiles/1129471783

The response includes detailed information about the profile, such as its name, description, type, state, policy configurations, application IDs, content IDs, enrollment license information, and device counts grouped by state. For detailed response schema, see GET /kc/v2/profiles/{profileId}.

Delete a profile

1. To delete a profile, make a DELETE request to the /kc/v2/profiles/{profileId} endpoint. This operation requires the kc.profile:manage scope.

2. In the request, specify the profileId as a path parameter.

For example, the following request deletes the profile with ID 1129471783:

DELETE /kc/v2/profiles/1129471783

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.