Setting the same lock screen passcode on all devices or a group via API

Android

You can set the same lock screen passcode on multiple managed devices using the Esper API. While there is no bulk passcode option in the Esper Console, you can apply a passcode to specific devices or to all devices in a group through the Command API.

Before you begin

Gather the following information from your Esper tenant:

• Tenant name — your Esper subdomain (for example, acme in acme-api.esper.cloud)
• Enterprise ID — found in Console → Company Settings
• Bearer token — generate one in Console → API Key Management
• Device UUID or Group UUID — see the relevant steps below

You will also need a tool to send API requests, such as cURL or Postman.

How to apply a passcode to specific devices

1. Find your device UUIDs in Devices & Groups → [Device Name] → Device Details.
2. Send a POST request to your API endpoint. Use this cURL example, replacing the placeholder values with your own:

   curl --location 'https://<tenant_name>-api.esper.cloud/api/v0/enterprise/<enterprise_id>/command/' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <Bearer_token>' \
   --data '{
    "command_type": "DEVICE",
    "devices": [ "<device_uuid>" ],
    "command": "RESET_LOCKSCREEN_PASSWORD",
    "command_args": {
    "new_lockscreen_password": "0000"
    }
   }'

3. To target multiple devices, add additional UUIDs to the "devices" array.
4. Confirm you receive a 200 OK or 202 Accepted response.

How to apply a passcode to all devices in a group

1. Find your group UUID in Devices & Groups → [Your Group] → Group Details.
2. Send a POST request using the following details:
   • Method: POST
   • URL: https://<tenant_name>-api.esper.cloud/api/v0/enterprise/<enterprise_id>/command/
   • Headers:
     • Content-Type: application/json
     • Authorization: Bearer <Bearer_token>
   • Request Body:

     {
      "command_type": "GROUP",
      "groups": [ "<group_uuid>" ],
      "command": "RESET_LOCKSCREEN_PASSWORD",
      "command_args": {
      "new_lockscreen_password": "0000"
      }
     }

3. Send the request and confirm you receive a 200 OK or 202 Accepted response.

How to verify the passcode was applied

1. On a target device, lock the screen and test the new passcode.
2. In the Esper Console, go to Devices & Groups → [Device Name] → Command History and confirm the RESET_LOCKSCREEN_PASSWORD command shows a Success status.

Troubleshooting

The API returns an authentication error:

• Verify your Bearer token has not expired.
• Confirm your token has Command API scope permissions.

The command shows Queued and does not transition to Success:

• The device may be offline. Commands are delivered when the device reconnects.
• Check the device status in Devices & Groups → [Device Name] → Device Details → Status.

The passcode does not change on the device despite a Success status:

• This command requires Device Owner (DO) mode enrollment. It will not work on Work Profile (PO) enrollments.
• Confirm your device is enrolled in Device Owner mode.

The command fails silently or returns an error:

• Confirm your passcode meets any existing password complexity policy set in your applied Blueprint.
• If the supplied passcode does not satisfy the policy, the command will fail.

Important security note

Do not store plaintext passcodes directly in API calls or scripts. Use a secrets management tool, such as environment variables or a vault, when automating this workflow.

Still need help?

If you continue to experience issues, contact Esper Support. Include the command ID from the API response and any relevant error messages.