> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/ai-agents/access-control/device-recovery.md).
# Device Recovery
The **Device Recovery** agent automates device recovery requests with identity verification and secure recovery key delivery to employees. The agent guides users step by step through the recovery process, handling device password resets and related asset management automatically - reducing the support load on your team while getting end users back into their devices quickly.
### What it does
* Triggered when a user requests device recovery
* Confirms the exact issue before triggering any workflow - if a user submits a vague message like "I'm locked," the AI clarifies whether it is a device lock, an account lock, or another situation before routing to the correct flow
* Verifies user identity via OTP or Okta Verify push notification before sharing any recovery key
* Retrieves device recovery key from MDM integration (JAMF, Intune, JumpCloud, or Kandji)
* Sends message with recovery key via Slack or Teams, with optional automatic expiry after one hour
* Updates the ticket with status and outcome
* Optionally performs automatic password reset when required (disabled by default)
### Triggers
**Event** - Runs when agent detects Device Recovery Request made by user.
### Approval
No approval required. The agent uses identity verification instead of approval workflow.
### Configuration
#### Identity Verification
Require users to verify their identity during device recovery. Choose from two verification methods:
* **One-Time Password (OTP)** - A one-time password is sent to the user's primary email address, and secondary email if available. The user must enter this code when prompted via direct message to verify their identity.
* **Okta Verify Push Notification** - Send a push notification to the user's Okta Verify app for quick and secure verification.
#### Auto Password Reset
Optionally enable automatic password reset for the user during the device recovery process. Automatic password reset is **disabled by default** - this reduces unintended disruption for end users who are simply recovering a device and do not need their password changed. You can enable it on a per-tenant basis through configuration if your workflow requires it.
#### Recovery Key Message Expiry
You can configure Harmony to automatically remove the recovery key from device recovery messages after one hour, reducing the risk of sensitive keys being exposed indefinitely in chat. When enabled, the original direct message sent to the end user is updated after 60 minutes to replace the recovery key with an expiry notice.
* **Optional toggle** - The expiry behaviour is off by default and can be enabled via the `expire_recovery_key_message` setting in the Device Recovery workflow configuration.
* **Automatic cleanup** - Once the ticket is resolved and the timer elapses, no trace of the key remains in the conversation.
#### MDM Provider Blocks
You can use dedicated MDM workflow blocks for each of your device management providers, giving the agent precise, provider-specific control over managed devices. The following providers are supported out of the box, each with their own set of blocks tailored to their capabilities:
| Provider | Available Blocks |
| -------------------- | --------------------------------------------------------- |
| **JAMF** | Get device, list devices, get recovery key, update device |
| **Microsoft Intune** | Get device, list devices, get recovery key, update device |
| **JumpCloud MDM** | Get device, list devices, update device |
| **Kandji** | Get device, list devices, get recovery key |
These blocks connect to their respective MDM integrations and can be combined within the Device Recovery workflow to automate end-to-end recovery scenarios - such as retrieving a Personal Recovery Key from JAMF for a locked Mac, or triggering recovery actions through Intune or Kandji - without leaving Harmony.
You can also retrieve a device's lock PIN directly through the Device Management API, making it easier to look up lock PIN information programmatically to support faster and more automated device management workflows.
#### Tenant Access Control
You can use tenant whitelist filtering to control which tenants have access to the device recovery password reset workflow template. This gives administrators precise control over which organisations can trigger password reset flows for device recovery, reducing the risk of unintended access across tenants.
#### Smarter Pre-Workflow Confirmation
Before triggering any recovery or reset workflow, Harmony confirms the exact issue the user is experiencing. When a user submits a vague or ambiguous message, the AI clarifies the situation before taking action:
* **Device lock** - routes to the Device Recovery workflow only after confirming it is a device-related issue
* **Account lock / IDP password expiration** - routes to the IDP Password Reset workflow only after confirming the lock type
* **Other or unclear situations** - the AI continues to gather context before proceeding
This prevents the wrong workflow from being triggered and reduces disruption caused by misclassified requests.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/ai-agents/access-control/device-recovery.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.