Before you start
- An Iru API token with MCP turned on and permissions that cover the calls below (recipe 1).
- The Mac is enrolled and its FileVault Library Item escrows the recovery key to Iru.
- Know whether your FileVault Library Item rotates keys after viewing. Viewing the key through the API counts as a view.
Prompt for your agent
Find the Mac used by [user name or serial number] in Iru. Show me its name, serial number and assigned user, then stop and wait for my approval. After I approve, retrieve its FileVault recovery key with GET /api/v1/devices/{device_id}/secrets/filevaultkey and show it to me once. Remind me that this counts as a view, which can start key rotation.
Steps
Find the Mac
Have the agent find the Mac by the user's name or the serial number and show you the device record before it goes further.
GET/api/v1/devicesSource: Iru API: List Devices
Retrieve the key after you approve
Retrieving the key through the API counts as a view and follows the same rotation setting as viewing it in the web app.
GET/api/v1/devices/{device_id}/secrets/filevaultkeyApproval requiredThe agent shows you the Mac and waits. Approve only when the user is ready to enter the key.
Source: Configure FileVault
Give the key to the user
Read the key to the user so they can unlock the Mac. To do the same in the web app, open the Device Record, select the Device Action Menu, then View FileVault2 recovery key.
Source: Configure FileVault
Check it worked
- Iru logs who viewed the key and when. The audit log lists access to sensitive data such as FileVault keys (
GET /api/v1/audit/events).
Common pitfalls
- With Rotate keys after viewing (hours) set, viewing the key starts the timer. When it runs out, Iru rotates the key on the Mac with the RotateFileVaultKey MDM command.
- With rotation after viewing off, the key still rotates on schedule if Automatically rotate keys is on.
- To force a new key on the Mac, run
sudo fdesetup changerecovery -personalin Terminal. Iru captures the new key if escrow is on.
FAQ
Which API call returns a FileVault recovery key?
GET /api/v1/devices/{device_id}/secrets/filevaultkey returns the recovery key for one Mac.
Does viewing the key through the API rotate it?
An API view counts as a view, so the Rotate keys after viewing (hours) setting applies and Iru rotates the key with the RotateFileVaultKey command.
Is access to the key logged?
Yes. The Activity audit log records access to FileVault keys, and GET /api/v1/audit/events returns those events.
Where is the key in the web app?
Open the Device Record, then the Device Action Menu, then View FileVault2 recovery key.