Assign SIM-Secure Lifetime License

Assign SIM-Secure for IoT Lifetime License to Devices
POST /devices/license/actions/assign

SIM-Secure for IoT binds SIMs to devices, safeguarding data usage and access to corporate networks. As your connected systems grow, so does your exposure to risk of SIM card misuse. SIM-Secure for IoT takes on the burden of securing the SIM of each device that connects to your network. SIM-Secure for IoT helps you:

  • Secure IoT sensors and devices, industrial equipment, and more by pairing each SIM card with a specific device.
  • Prevent unauthorized devices from connecting to your private network.

Once the SIM-Secure for IoT feature is applied to a SIM, it is bound to the device in which it is inserted. If the SIM is removed from the original device and placed into a second device, the SIM-Secure for IoT feature recognizes that the SIM is in the wrong device, and prevents the device from connecting to the network. The SIM must be in the original device that it was paired with to allow a network connection.

Contents

See also:
Retrieve Device Information
Activate Devices

Uses and Requirements

To have a SIM-Secure for IoT, lifetime license, assigned devices must meet the following requirements:

  • Devices must be in an active state.
  • Devices must be onboarded into ThingSpace/ThingSpace Connectivity Management.
  • Devices must be visible within the ThingSpace Manage web portal.
  • Devices must belong to the account making the assignment request.
  • Devices must be 4G devices. Only 4G devices are eligible for SIM-Secure for IoT license assignment.

NOTE: You cannot remove a lifetime license once you have assigned it to a SIM.

Request Components

HTTP Request

POST /api/m2m/v1/devices/license/actions/assign

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name Data Type Description
Authorization
required
string HTTP Authorization bearer token.
VZ-M2M-Token
required
string A valid session token returned by POST /session/login.
Content-Type
required
string Must be application/json.

Request Body

The request body identifies the account name, SKU number, and a list of devices to which you want to assign a SIM-Secure for Iot license.

Parameter Name Data Type Description
accountName
required
string The name of a billing account.
This parameter is required only if the UWS account used for the current API session has access to multiple accounts. An account name is usually numeric, and must include any leading zeros.
skuNumber
required
string (20 characters max string) The Stock Keeping Unit (SKU). The skuNumber for SIM-Secure lifetime license is “SIMSEC-Iot-LT”.
devices
required
array of deviceIds objects A list of 4G devices.
kind,
id

required
strings For 4G devices, IMEI (decimal, up to 15 digits) and ICCID (decimal, up to 20 digits), in that order.

Example Request Body

{
  "accountName": "0123456788-00001",
  "skuNumber": "SIMSec-IoT-Lt",
   "devices": [
    {
      "deviceIds": [
        {
          "id": "123456789012345",
          "kind": "imei"
        },
        {
          "id": "12345678901234567890",
          "kind": "iccid"
        }
      ]
    },
    {
      "deviceIds": [
        {
          "id": "123456789012346",
          "kind": "imei"
        },
        {
          "id": "12345678901234567891",
          "kind": "iccid"
        }
      ]
    }
  ]
}


Success Responses

Status 200

Parameter Name Data Type Description
requestId string A unique string that associates the request with the results that are sent via a callback message.
ThingSpace sends a separate callback message for each device that was in the request indicating whether the operation succeeded for that device. All of the callback messages have the same requestId.

Example Success Response

{"requestId": "c3f3d17c-79ff-4b35-82df-94446785b6e0"}

Example Success Callback Response

You receive a callback when you initiate SIM-Secure for IoT license assignment to lines and get an asynchronous response.

{
    "username" : "NCAzVE9NIEhQTiBT",
    "password" : "gewWBmxcffKcISjleWnjwXPrgavpFNdKVpNUvazX",
    "requestId" : " c3f3d17c-79ff-4b35-82df-94446785b6e0",
    "deviceIds" : [
      {
         "id" : "123456789012345",
         "kind" : "imei"
      }
    ],
    "deviceResponse" : {
       "deviceSkuSubscriptionResponse" :
       {
          "accountName" : "0123456788-00001",
          "skuNumber" : "SIMSec-IoT-Lt"
       }
     },
    "comment" : "Success"
}


Failure Responses

Error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error Codes and Messages

Error Code Error Message Description
REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST FAILED: Device already has license assigned. You attempted to assign a license to a device that already has a license assigned.
UnifiedWebService.REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST_FAILED: At least one device exists with Assigned or Pending Assignment or Pending UnAssignment license status. You attempted to assign a license to a device that has already had a license assigned.
Carrier.Service.INPUT_INVALID.SKUNumber.NotDefined skuNumber is a required field. Your request did not include the skuNumber.
Carrier.Service.INPUT_INVALID.Action.NotDefined Action is required. Your request did not include an action.
UnifiedWebService.REQUEST_FAILED.CarrierRequestUnsuccessful REQUEST_FAILED: Devices not found for the specified IMEI and ICCID. Verify the IMEI and ICCID for the device.
Carrier.Service.INPUT_INVALID.DeviceGroupName.NotSupported The Device Group Name is not supported. The device group in the request does not exist.
Carrier.Service.INPUT_INVALID.Action.Invalid The action was not recognized as valid. Verify that your POST request has an “assign” action to assign the license.
UnifiedWebService.INPUT_INVALID.DeviceNotDefined A device must be defined. Your request did not include device information.
CarrierService.INPUT_INVALID.DeviceIdentifierCollection.Null A device identifier collection may not be null. Your request did not specify device identifiers.
UnifiedWebService.INPUT_INVALID.Unassign.NotSupported The unassign action is not supported for SIM-Secure lifetime. You cannot unassign a lifetime license for SIM-Secure.
INPUT_INVALID.InsufficientLicense.Invalid You do not have required licenses to perform this action. The number of devices in your request exceeds the number of available licenses.

HTTP Error Codes

Error Code Error Message Description
401 Unauthorized You are not allowed to perform this operation.
404 Not found Information that is provided, such as account name or device id, is not found.
405 Method not allowed. You used the wrong REST method to call the API.
406 Not acceptable. For example, you might have tried to assign a license to a non-existent device.
412 Precondition failed. You might not have purchased licenses, or have not purchased enough licenses for the devices you are trying to assign. No licenses have been assigned.
500 Internal server error. Service calls other internal services, but has received an error.
501 Not implemented. The feature is not available. For example, if you tried to assign a SIM-Secure for IoT license to a 5G device.