Security & Recovery Management

The security of a Customer Custody wallet relies on the user's PIN. Planbok provides robust tools for managing this PIN and recovering the account if the PIN is forgotten.

1. Setting Up Recovery

Users typically set up their recovery method during the initial Onboarding & PIN Setup flow in the Gateway. However, if a user skips this step or needs to re-configure it, you can initiate the process manually via the API.

Endpoint: POST /v2/customers/{id}/recovery
Headers:

• PLANBOK-X-API-KEY: <your_api_key>

Request Body:

Code
{
  "redirectUrl": "https://yourapp.com/security/recovery-setup-complete"
}

2. Updating a Known PIN

If a user knows their current PIN but wants to change it, use the Update PIN flow.

Endpoint: POST /v2/customers/{id}/update-pin

Workflow:

1. Authorize: The user enters their Current PIN on the Gateway.
2. Assign: The user selects and confirms their New PIN.
3. Reshard: The Gateway re-encrypts the user's shard with the new PIN.

3. Resetting a Forgotten PIN

If a user has forgotten their PIN, they can reset it using the recovery method established in Step 1.

Endpoint: POST /v2/customers/{id}/reset-pin

Workflow:

1. Verify Identity: The user completes a recovery challenge (e.g., verifying an email code or answering security questions).
2. New PIN: Once verified, the user is prompted to set a new PIN.
3. Restoration: The system uses the recovery shard to reconstruct and re-protect the user's access.

4. Exporting Private Keys

Planbok Customer Custody Wallets are fully non-custodial. Users can export their full private keys at any time for use in external wallets (e.g., MetaMask, Solana Phantom).

Endpoint: POST /v2/customers/{id}/export-private-keys

Workflow:

1. Authorize: The user enters their PIN on the Gateway to authorize the export.
2. MPC Reconstruction: The Planbok node and the Gateway (using the unlocked user shard) reconstruct the original private key.
3. Delivery: The CSV payload (containing addresses and private keys) is returned directly to the Gateway interface for the user to download. The user can open this file directly with any spreadsheet software or text editor, but must be careful to store it securely and never share it with anyone.

Best Practices for Security

• Mandatory Recovery Setup: Users cannot create wallets or sign transactions until they have completed the Recovery Setup.
• Session Security: Redirect URLs should point to secure, authenticated pages in your application.
• Monitoring: Listen for customer.pin_updated or customer.recovery_setup webhooks to keep your user's security status up to date in your own database.

Conclusion

You have completed the Customer Custody quickstart guides! You are now ready to build secure, non-custodial wallet experiences for your users.