Get FileVault Recovery Key
Retrieve FileVault recovery keys for macOS devices managed by Kandji
Retrieves FileVault recovery keys for the requestor's macOS devices enrolled in Kandji. 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 Kandji
- 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 Kandji API configuration as the Get Device Information tool:
- Kandji API Token with Device Read permissions
- Kandji Subdomain (e.g.,
yourcompanyfromyourcompany.api.kandji.io) - Region (US or EU)
Additionally, the API token must have Secrets Read permissions to access FileVault keys.
Setup
Step 1: Verify API Token Permissions
- Log into Kandji as an administrator
- Go to Settings > Access > API Tokens
- Click on your existing Risotto API token
- Click the Permissions tab
- Under Devices, ensure Read permissions are enabled
- Under Secrets, enable Read permissions
- Click Save
Step 2: Connect Iru (Kandji) in Risotto
Skip this step if Iru is already connected for your organization.
- In the Risotto dashboard, navigate to Settings > Integrations > Iru
- On the Iru card, click Connect
- Enter your Kandji API details:
- Subdomain: Your Kandji subdomain (without the API domain), for example
acme - API Token: Your Kandji API token (with Secrets Read permission)
- Region: United States (US) or European Union (EU)
- Subdomain: Your Kandji subdomain (without the API domain), for example
- Click Save
Step 3: Enable the Tool in Risotto
- Select Tools in the sidebar
- In the Tool groups list, select Iru
- Find Iru 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 Kandji. This ensures users can only retrieve keys for their own devices.
Multiple Devices
If you have multiple Macs enrolled in Kandji:
- 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 Kandji
- 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 Kandji
- 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 Kandji
- 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 Token Security
- Store API tokens securely (Risotto encrypts them at rest)
- Use dedicated service account for API token creation
- Enable Secrets Read permission only on tokens that need it
- Rotate tokens periodically (every 90 days recommended)
Troubleshooting
No devices found assigned to your email
Causes:
- Device is not assigned to you in Kandji
- Device is not enrolled in Kandji
- Email mismatch between ticket and Kandji
Solution:
- Verify your device is enrolled in Kandji
- Ensure device is assigned to your email in Kandji
- Contact IT to verify device assignment
No FileVault recovery key found
Causes:
- Device is not encrypted with FileVault
- Recovery key was not escrowed to Kandji
- API token lacks Secrets Read permission
Solution:
- Verify FileVault is enabled on your device
- Check that recovery key was escrowed to Kandji
- Contact IT to verify tool configuration
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 token
Solution:
- Contact IT administrator to verify Kandji integration
- Tool configuration may need to be updated
API Details
Endpoints Used
GET /api/v1/devices?user_email={email}- Search devices by requestor emailGET /api/v1/devices/{device_id}- Get device detailsGET /api/v1/devices/{device_id}/secrets/filevaultkey/- Retrieve recovery key
Required Permissions
- Devices: Read - Search and retrieve device information
- Secrets: Read - Access FileVault recovery keys
Something wrong or missing? Report an issue · View as Markdown