Get FileVault Recovery Key
Retrieve FileVault recovery keys for macOS devices managed by JAMF Pro
Retrieves FileVault recovery keys for the requestor's macOS devices enrolled in JAMF Pro. The recovery key allows users to unlock their encrypted drives when they forget their password.
To watch one request from start to finish (a sign-in to verify, then the key by direct message) and how to set it up, see the video Example: recover a FileVault key.
Overview
This tool enables self-service retrieval of FileVault recovery keys through Risotto. Users can retrieve keys for their own devices when locked out. The tool:
- Automatically searches for devices assigned to the ticket requestor
- Verifies the device is macOS (FileVault only works on Mac)
- Retrieves the escrowed recovery key from JAMF Pro
- Logs all access for security audit trails
- Security: Users can only retrieve keys for devices assigned to them
Prerequisites
Before using this tool, you need the same JAMF Pro API configuration as the Get Device Information tool:
- JAMF Pro Server URL (e.g.
https://yourcompany.jamfcloud.com) - API Client ID and Client Secret (OAuth credentials)
- An API Role with the privileges listed below
Additionally, the API Role must include the View Disk Encryption Recovery Key privilege to access FileVault keys.
Setup
Step 1: Update the API Role Privileges
If you already configured the Get Device Information tool, update its API Role to add the FileVault privilege:
- Log into your JAMF Pro server as an administrator
- Navigate to Settings (gear icon) > System > API Roles and Clients
- Click the API Roles tab and open the role used by Risotto (e.g.
Risotto Computer Inventory Reader) - Ensure the following privileges are selected:
- Read Computers
- View Disk Encryption Recovery Key
- Click Save
Step 2: Connect JAMF Pro in Risotto
Skip this step if JAMF Pro is already connected for your organization.
- In the Risotto dashboard, navigate to Settings > Integrations > Jamf
- On the JAMF Pro card, click Connect
- Enter your JAMF Pro credentials:
- Server URL: Your JAMF Pro server URL (without trailing slash), for example
https://yourcompany.jamfcloud.com - Client ID: Your JAMF Pro API Client ID
- Client Secret: Your JAMF Pro API Client Secret
- Server URL: Your JAMF Pro server URL (without trailing slash), for example
- Click Save
Step 3: Enable the Tool in Risotto
- Select Tools in the sidebar
- In the Tool groups list, select Jamf
- Find JAMF Pro Get FileVault Recovery Key and click Enable
- Optionally, open the tool and click Edit to change its settings:
- Requires Approval: Require human approval before the tool runs (recommended)
- Restrict to Requestor Only: Only operate on devices assigned to the ticket requestor. On by default.
- Send via DM Only: Send the key to the requestor in a Slack DM, not in the ticket thread. If Risotto cannot send the DM, it does not post the key in the thread. The tool fails, and the agent escalates the ticket.
- Click Save
How It Works
Automatic Requestor Identification
The tool automatically identifies the requestor from the ticket context and searches for devices assigned to that user in JAMF Pro (matching on the user's email). This ensures users can only retrieve keys for their own devices.
Multiple Devices
If you have multiple Macs enrolled in JAMF Pro:
- Without serial number: Tool lists all your devices with their serial numbers and asks you to specify which one
- With serial number: Tool retrieves the key for your specific device matching that serial
Configuration Options
| Parameter | Type | Required | Description |
|---|---|---|---|
serial_number | TEXT | No | Device serial number (only needed if you have multiple devices) |
The tool automatically uses the requestor's email from the ticket context to find their devices.
Response Format
Successful Retrieval
**FileVault Recovery Key for MacBook-Pro-2023**
**Device:** MacBook-Pro-2023
**Serial:** C02XY1ZHJG5H
**User:** john.smith@company.com
🔑 **Recovery Key:**
`XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`
⚠️ **Important:** This key allows full disk decryption. Handle with care and do not share unnecessarily.
Multiple Devices Found
You have 2 devices enrolled:
C02XY1ZHJG5H, C02AB2CDJG5K
Please specify serial_number to get the FileVault key for a specific device.
No Key Available
No FileVault recovery key found for MacBook-Pro-2023.
Possible reasons:
- Device is not encrypted with FileVault
- Recovery key was not escrowed to JAMF Pro
- Device needs to regenerate its recovery key
Usage Examples
Example 1: Single device - automatic retrieval
User Request:
"I'm locked out of my MacBook and can't remember my password"
What Happens:
- Tool automatically finds device assigned to requestor
- Verifies device is macOS
- Retrieves FileVault recovery key from JAMF Pro
- Returns key with device details and security warning
Example 2: Multiple devices - disambiguation needed
User Request:
"I need my FileVault key"
First Response:
You have 2 devices enrolled:
C02XY1ZHJG5H, C02AB2CDJG5K
Please specify serial_number to get the FileVault key for a specific device.
User Clarifies:
"I need the key for C02XY1ZHJG5H"
What Happens:
- Tool searches requestor's devices
- Uses serial number to identify the correct device
- Returns key for that specific device
Security Considerations
Access Control
- Self-Service Only: Users can only retrieve keys for devices assigned to them in JAMF Pro
- Approval Workflows: Enable human approval for additional security layer (recommended)
- Audit Logging: All key access is logged with device and requester details
- Ticket Context: Tool only works within support ticket context
Best Practices
- Enable Approval: Configure the tool to require human approval for additional security
- Monitor Usage: Review logs regularly to track key retrieval
- Secure Handling: Keys allow full disk decryption - handle with care
- Password Reset: Users should reset their password after using the recovery key
API Credential Security
- Store API credentials securely (Risotto encrypts them at rest)
- Use a dedicated API Client for Risotto rather than sharing one across integrations
- Grant only the privileges required (least privilege)
- Rotate the client secret periodically (every 90 days recommended)
Troubleshooting
No devices found assigned to your email
Causes:
- Device is not assigned to you in JAMF Pro
- Device is not enrolled in JAMF Pro
- Email mismatch between the ticket and JAMF Pro user record
Solution:
- Verify your device is enrolled in JAMF Pro
- Ensure the device's assigned user email matches your ticketing email
- Contact IT to verify device assignment
No FileVault recovery key found
Causes:
- Device is not encrypted with FileVault
- Recovery key was not escrowed to JAMF Pro
- API Role lacks the View Disk Encryption Recovery Key privilege
Solution:
- Verify FileVault is enabled on your device
- Confirm a Disk Encryption configuration profile is scoped to the device with Escrow Personal Recovery Key enabled
- Contact IT to verify the API Role has the required privilege
Cannot retrieve FileVault key for this device
Cause: Device platform is not macOS
Solution:
- FileVault is only available on Mac devices
- For Windows devices, contact IT for BitLocker recovery
Authentication failed
Cause: Invalid or expired API credentials, or the API Client is disabled
Solution:
- Verify the Client ID and Secret in Risotto match what's shown in JAMF Pro
- Check that the API Client is enabled in Settings > System > API Roles and Clients
- If the client secret was rotated in JAMF Pro, update the credentials in Risotto
API Details
Required Privileges
- Read Computers — Search and retrieve device information
- View Disk Encryption Recovery Key — Access FileVault recovery keys
Something wrong or missing? Report an issue · View as Markdown