Docs

Integrations / Devices / Iru (formerly Kandji)

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:

  1. Kandji API Token with Device Read permissions
  2. Kandji Subdomain (e.g., yourcompany from yourcompany.api.kandji.io)
  3. Region (US or EU)

Additionally, the API token must have Secrets Read permissions to access FileVault keys.

Setup

Step 1: Verify API Token Permissions

  1. Log into Kandji as an administrator
  2. Go to Settings > Access > API Tokens
  3. Click on your existing Risotto API token
  4. Click the Permissions tab
  5. Under Devices, ensure Read permissions are enabled
  6. Under Secrets, enable Read permissions
  7. Click Save

Step 2: Connect Iru (Kandji) in Risotto

Skip this step if Iru is already connected for your organization.

  1. In the Risotto dashboard, navigate to Settings > Integrations > Iru
  2. On the Iru card, click Connect
  3. 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)
  4. Click Save

Step 3: Enable the Tool in Risotto

  1. Select Tools in the sidebar
  2. In the Tool groups list, select Iru
  3. Find Iru Get FileVault Recovery Key and click Enable
  4. 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.
  5. 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

ParameterTypeRequiredDescription
serial_numberTEXTNoDevice 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:

  1. Tool automatically finds device assigned to requestor
  2. Verifies device is macOS
  3. Retrieves FileVault recovery key from Kandji
  4. 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:

  1. Tool searches requestor's devices
  2. Uses serial number to identify the correct device
  3. 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

  1. Enable Approval: Configure the tool to require human approval for additional security
  2. Monitor Usage: Review logs regularly to track key retrieval
  3. Secure Handling: Keys allow full disk decryption - handle with care
  4. 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:

  1. Verify your device is enrolled in Kandji
  2. Ensure device is assigned to your email in Kandji
  3. 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:

  1. Verify FileVault is enabled on your device
  2. Check that recovery key was escrowed to Kandji
  3. 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 email
  • GET /api/v1/devices/{device_id} - Get device details
  • GET /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