Home / Tag API /

Get started

Last updated June 17th, 2026

This guide provides step-by-step instructions to integrate Tag API capabilities into your web services.

Before you begin

Before you start the integration process, ensure you have the following:

  • A valid Samsung Knox account with Tag API access enabled
  • Familiarity with REST APIs and OAuth 2.0 authentication mechanisms
  • A development environment capable of making HTTP requests

Step 1: Sign up for Tag API access

  1. Register for a Samsung Knox account.
  2. Log in to your account and apply for the Tag API access.

Step 2: Request API access

To request access to the Tag API, send an email to knoxapi@samsungknox.com with the subject line “Tag API access request”.

Step 3: Generate access token

  1. Open Knox Developer Portal.
  2. Register a cloud app to obtain your client credentials.
  3. Follow the OAuth 2.0 authentication flow to generate your access token.

Ensure that your application requests the following scopes:

  • tag: For all common tag operations
  • tag.tags:view: For retrieving common tag information
  • tag.tags:manage: For creating, updating, and deleting common tags

Step 4: Test your access token by creating your first common tag

Ensure that your access token is correctly configured by making a test call to create a new common tag:

curl --location 'https://api.samsungknox.com/tag/v1/tags?customerId={CUSTOMER_ID}' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}' \
     --data '{
         "name": "Test Devices",
         "description": "Devices for testing purposes"
     }'

A successful response will look like this:

{
  "result": 201,
  "code": "20100000",
  "message": "SUCCESS",
  "data": {
    "total": 1,
    "tags": [
      {
        "id": "tag-id-456",
        "name": "Test Devices",
        "description": "Devices for testing purposes",
        "predefinedType": "MANUAL",
        "assignedDeviceCount": 0,
        "createdOn": 1778656444000,
        "modifiedOn": 1778656444000
      }
    ]
  }
}

Step 5: Assign common tags to devices in bulk

Once you have created the necessary tags, assign them to multiple devices using the bulk assignment endpoint:

curl --location 'https://api.samsungknox.com/tag/v1/devices/bulkAssign' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}' \
     --data '{
         "deviceIds": [
             "device-id-1",
             "device-id-2",
             "device-id-3"
         ],
         "tags": [
             {
                 "tagId": "tag-id-456"
             }
         ]
     }'

A successful response will look like this:

{
  "result": 200,
  "code": "20000000",
  "message": "SUCCESS",
  "data": {
    "successCount": 3,
    "failCount": 0,
    "downloadUrl": "https://api.samsungknox.com/download/results-123.csv"
  }
}

Step 6: Retrieve existing common tags assigned to devices

To see how many devices are assigned per tag, use the following endpoint:

curl --location 'https://api.samsungknox.com/tag/v1/tags?customerId={CUSTOMER_ID}' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}'

A successful response will look like this:

{
  "result": 200,
  "code": "20000000",
  "message": "SUCCESS",
  "data": {
    "totalCount": 5,
    "data": [
      {
        "id": "tag-id-456",
        "name": "Test Devices",
        "description": "Devices for testing purposes",
        "predefinedType": "MANUAL",
        "assignedDeviceCount": 3,
        "createdOn": 1778656444000,
        "modifiedOn": 1778656445999
      }
    ],
    "pageSize": 10,
    "page": 0
  }
}

Step 7: Update or delete common tags

You can update or delete tags as needed using the following endpoints:

Update a common tag

To modify an existing tag’s name or description, send a PUT request with the updated tag details:

curl --location 'https://api.samsungknox.com/tag/v1/tags/tag-id-456' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}' \
     --data '{
         "name": "Production Devices",
         "description": "Devices in production environment"
     }'

A successful response will look like this:

{
  "result": 200,
  "code": "20000000",
  "message": "SUCCESS",
  "data": {
    "id": "tag-id-456",
    "name": "Production Devices",
    "description": "Devices in production environment",
    "predefinedType": "MANUAL",
    "assignedDeviceCount": 3,
    "createdOn": 1778656444000,
    "modifiedOn": 1778656450000
  }
}

Delete a common tag

To permanently delete a tag, send a DELETE request with the tag ID:

curl --location 'https://api.samsungknox.com/tag/v1/tags/tag-id-456' \
     --header 'Authorization: Bearer {ACCESS_TOKEN}'

A successful response will look like this:

{
  "result": 204,
  "code": "20400000",
  "message": "SUCCESS",
  "data": "Ok"
}

Troubleshooting

If you encounter issues with your integration, check these common problems:

  1. Authentication errors: Verify that your access token is valid and has not expired. By default, tokens expire after 30 minutes.
  2. Permission errors: Make sure your application has the required scopes (tag, tag.tags:view, or tag.tags:manage).
  3. Invalid customer ID: Ensure you are using the correct customer ID for your company account.
  4. Rate limit exceeded: The API has a rate limit of 25 requests per second. If you exceed this limit, wait before making additional requests.

For more information on error codes, see Error codes.

On this page

Is this page helpful?