--- name: cumulocity-manage-device-credentials description: "List the device users of your tenant, find the device user that a device authenticates with, and disable or enable it to block or allow the login of the device. Use when the user wants to find the device user of a device, or block or allow the login of a device." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage device credentials Source: https://cumulocity.com/docs/skills/device-management/manage-device-credentials/ Sector: Skills, Device management & connectivity Release: Latest Description: List the device users of your tenant, find the device user that a device authenticates with, and disable or enable it to block or allow the login of the device. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) A device that is registered with platform credentials authenticates as a device user. The platform creates this user during the bootstrap, when the device requests its credentials, see [Step 0: Request device credentials](https://cumulocity.com/docs/device-integration/device-integration-rest/#step-0-request-device-credentials). The device user owns the managed object of the device. The username of a device user starts with `device_`. The part after `device_` is the ID that the device used for its registration. It is not the name of the device, not its managed object ID, and not its IMEI. Do not build a username from these values. Read it from the device instead, see [To find the device user of a device](https://cumulocity.com/docs/skills/device-management/manage-device-credentials/#to-find-the-device-user-of-a-device). When you disable a device user, the device can no longer log in or send API requests. The managed object and the registration of the device stay unchanged, and you can enable the device user again. > **Requirements:** > ROLES & PERMISSIONS: > > * To list and read device users: ROLE_USER_MANAGEMENT_READ or ROLE_USER_MANAGEMENT_CREATE > * To disable and enable device users: ROLE_USER_MANAGEMENT_ADMIN > * To find the device user of a device: ROLE_INVENTORY_READ, and ROLE_IDENTITY_READ to find the device by an external ID The examples use `` for the ID of your tenant, `` for the managed object ID of the device, and `` for the username of the device user. ### To list the device users {#to-list-the-device-users} Send a [Retrieve all users for a specific tenant](https://cumulocity.com/api/core/#operation/getUserCollectionResource) request with `onlyDevices=true`: ```http GET /user//users?onlyDevices=true&pageSize=100 ``` The platform returns HTTP 200 and the device users in the `users` array, each with its `userName` and its `enabled` state. Without `onlyDevices=true`, the list contains no device users. To narrow the list, add one of the following parameters: * `username`: The beginning of the username or the full username, for example `username=device_0000`. The search is case-insensitive. * `usernameContains`: A part of the username with at least 3 characters. The search is case-insensitive. You cannot combine `username` and `usernameContains` in one request. If the `users` array is empty, no device on your tenant is registered with platform credentials. ### To find the device user of a device {#to-find-the-device-user-of-a-device} 1. If you know the device only by an external ID, such as its IMEI or serial number, find its managed object ID first. Send a [Retrieve a specific external ID](https://cumulocity.com/api/core/#operation/getExternalIDResource) request with the type and the value of the external ID, here the IMEI ``: ```http GET /identity/externalIds/c8y_IMEI/ ``` The type of an IMEI is `c8y_IMEI`, the type of a serial number is `c8y_Serial`. The platform returns HTTP 200, and `managedObject.id` is the ``. If the platform returns HTTP 404, the external ID is not registered. 2. Send a [Retrieve the username and state of a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectUserResource) request: ```http GET /inventory/managedObjects//user ``` The platform returns HTTP 200 with the `userName` of the owner of the device and its `enabled` state. If the `userName` starts with `device_`, it is the ``. If the `userName` is missing, empty, or does not start with `device_`, a regular user owns the device, and the device has no device user. Do not disable that user. If the platform returns HTTP 404, the device does not exist. ### To read a device user {#to-read-a-device-user} Send a [Retrieve a specific user for a specific tenant](https://cumulocity.com/api/core/#operation/getUserResource) request: ```http GET /user//users/ ``` The platform returns HTTP 200 and the user with its `userName` and its `enabled` state. If the platform returns HTTP 404, the user does not exist. Check that you read the username from the device. ### To disable a device user {#to-disable-a-device-user} Send an [Update a specific user for a specific tenant](https://cumulocity.com/api/core/#operation/putUserResource) request: ```http PUT /user//users/ Content-Type: application/json Accept: application/json { "enabled": false } ``` The platform returns HTTP 200 and the user with `"enabled": false`. The device cannot log in anymore. If the platform returns HTTP 403, you are missing the permission to update this user. If it returns HTTP 404, the user does not exist. ### To enable a device user again {#to-enable-a-device-user-again} Send an [Update a specific user for a specific tenant](https://cumulocity.com/api/core/#operation/putUserResource) request: ```http PUT /user//users/ Content-Type: application/json Accept: application/json { "enabled": true } ``` The platform returns HTTP 200 and the user with `"enabled": true`. The device can log in again. In the Device Management application, you manage device users on the **Device credentials** page, see [Managing device credentials](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-device-credentials). ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /user/{tenantId}/users](https://cumulocity.com/api/core/#operation/getUserCollectionResource): Retrieve all users for a specific tenant - [GET /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/getExternalIDResource): Retrieve a specific external ID - [GET /inventory/managedObjects/{id}/user](https://cumulocity.com/api/core/#operation/getManagedObjectUserResource): Retrieve the username and state of a specific managed object - [GET /user/{tenantId}/users/{userId}](https://cumulocity.com/api/core/#operation/getUserResource): Retrieve a specific user for a specific tenant - [PUT /user/{tenantId}/users/{userId}](https://cumulocity.com/api/core/#operation/putUserResource): Update a specific user for a specific tenant ## Linked from the documentation - [Managing device data > Managing device credentials](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-device-credentials)