--- name: cumulocity-register-device description: "Create a registration request for a device that fetches its own credentials, wait until the device connects, accept the request, and find the managed object that the device creates. Use when the user wants to connect a new device to the platform with a registration request." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Register a device Source: https://cumulocity.com/docs/skills/device-management/register-device/ Sector: Skills, Device management & connectivity Release: Latest Description: Create a registration request for a device that fetches its own credentials, wait until the device connects, accept the request, and find the managed object that the device creates. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) To connect a device that fetches its own credentials, you register its unique ID in a new device request. The device then asks the platform for credentials with this ID. After you accept the request, the platform generates the credentials and sends them to the device. The device uses them to create its own managed object. A new device request has one of the following statuses: * **WAITING_FOR_CONNECTION**: You created the request. The device has not asked for its credentials yet. * **PENDING_ACCEPTANCE**: The device asked for its credentials. You must accept the request. * **ACCEPTED**: You accepted the request. The device receives its credentials with its next request. A new device request carries no password. To register devices with a password that you define, or to register devices from a CSV file, use the bulk registration, see [Bulk device registration](https://cumulocity.com/docs/device-management-application/registering-devices/#bulk-device-registration). For the same procedure in the Device Management application, see [Single device registration](https://cumulocity.com/docs/device-management-application/registering-devices/#single-device-registration). Do not create the managed object, the external ID, or the user of the device yourself. The device creates them after you accept the request. > **Requirements:** > ROLES & PERMISSIONS: > > * To create and accept new device requests: ROLE_DEVICE_CONTROL_ADMIN > * To read new device requests: ROLE_DEVICE_CONTROL_READ > * To find the device by its external ID: ROLE_IDENTITY_READ > * To delete new device requests: ROLE_USER_MANAGEMENT_ADMIN The examples use `` for the unique ID of the device, for example its serial number or, for mobile devices, the IMEI. To register several devices, follow the procedures once per device. ### To create the new device request {#to-create-the-new-device-request} Send a [Create a new device request](https://cumulocity.com/api/core/#operation/postNewDeviceRequestCollectionResource) request: ```http POST /devicecontrol/newDeviceRequests Content-Type: application/json Accept: application/json { "id": "" } ``` To assign the device to a group, add `groupId` with the ID of the group. The platform returns HTTP 201 and the request with `"id": ""` and `"status": "WAITING_FOR_CONNECTION"`. If the platform returns HTTP 422 with a message that the request already exists, a request for this ID is already registered. Do not create a second one. Continue with the next procedure. ### To wait for the device to connect {#to-wait-for-the-device-to-connect} Turn on the device. The device asks for its credentials with its ID and the bootstrap credentials of the platform, see [Step 0: Request device credentials](https://cumulocity.com/docs/device-integration/device-integration-rest/#step-0-request-device-credentials). The device sends this request, not you. Send a [Retrieve a specific new device request](https://cumulocity.com/api/core/#operation/getNewDeviceRequestResource) request: ```http GET /devicecontrol/newDeviceRequests/ ``` Repeat the request every 10 seconds until the `status` is PENDING_ACCEPTANCE, for example for 2 minutes. If the status is still WAITING_FOR_CONNECTION after this time, the device has not connected yet. The request stays valid, and the device can connect later. Check again later before you accept the request. ### To accept the request {#to-accept-the-request} Accept the request only when its status is PENDING_ACCEPTANCE. Send an [Update a specific new device request status](https://cumulocity.com/api/core/#operation/putNewDeviceRequestResource) request: ```http PUT /devicecontrol/newDeviceRequests/ Content-Type: application/json Accept: application/json { "status": "ACCEPTED" } ``` If the device sent a security token when it asked for its credentials, add the same token as `securityToken` to the request body. The platform compares both tokens. Whether a token is needed depends on the security token policy of your tenant, see [Security token policy](https://cumulocity.com/docs/device-management-application/registering-devices/#security-token-policy). The platform returns HTTP 200 and the request with `"status": "ACCEPTED"`. The device receives its credentials with its next request and then creates its own managed object. ### To find the new device {#to-find-the-new-device} This procedure assumes that the device uses its ID as an external ID of type `c8y_Serial`. Send a [Retrieve a specific external ID](https://cumulocity.com/api/core/#operation/getExternalIDResource) request: ```http GET /identity/externalIds/c8y_Serial/ ``` The platform returns HTTP 200. The `managedObject.id` property of the response is the ID of the new device. If the platform returns HTTP 404, the device has not created its managed object yet. Repeat the request every 10 seconds, for example for 2 minutes. When the device creates its managed object depends on the device. ### To cancel a new device request {#to-cancel-a-new-device-request} To cancel a request that is not completed, send a [Delete a specific new device request](https://cumulocity.com/api/core/#operation/deleteNewDeviceRequestResource) request: ```http DELETE /devicecontrol/newDeviceRequests/ ``` The platform returns HTTP 204. If it returns HTTP 404, the request does not exist. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /devicecontrol/newDeviceRequests](https://cumulocity.com/api/core/#operation/postNewDeviceRequestCollectionResource): Create a new device request - [GET /devicecontrol/newDeviceRequests/{requestId}](https://cumulocity.com/api/core/#operation/getNewDeviceRequestResource): Retrieve a specific new device request - [PUT /devicecontrol/newDeviceRequests/{requestId}](https://cumulocity.com/api/core/#operation/putNewDeviceRequestResource): Update a specific new device request status - [GET /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/getExternalIDResource): Retrieve a specific external ID - [DELETE /devicecontrol/newDeviceRequests/{requestId}](https://cumulocity.com/api/core/#operation/deleteNewDeviceRequestResource): Delete a specific new device request ## Linked from the documentation - [Registering devices > Single device registration](https://cumulocity.com/docs/device-management-application/registering-devices/#single-device-registration)