Introduction to Customer Custody

The Customer Custody model is designed for applications where end-users maintain total control over their assets. Unlike the Organizational model where you manage the signing entropy, in Customer Custody, the user's PIN is required to authorize every critical action.

How it Works: The Challenge-Response Model

Because security is non-custodial, Planbok uses a Challenge-Response architecture. This ensures that the user's PIN never touches your servers or Planbok's backend in plain text.

The 4-Step Integration Flow

Any action that requires user authorization (like wallet creation or signing a transaction) follows this pattern:

1. Request Challenge: Your backend calls the Planbok API to initiate an action (e.g., provision wallet).
2. Generate Gateway URL: Planbok returns a challengeId and a unique redirectUrl pointing to the Planbok Gateway (gateway.planbok.io).
3. User Verification: You redirect your user to the Gateway URL. The user enters their PIN on this secure, isolated page.
4. Completion & Callback: Once verified, the Gateway redirects the user back to your application with the completed challenge status.

The Planbok Gateway

The Planbok Gateway is a secure, white-labeled interface handled by our MPC nodes. It serves three main purposes:

• Zero-Knowledge PIN Entry: It collects and hashes the user's PIN locally, sending only the necessary cryptographic shards to the MPC nodes.
• Visual Confirmation: It shows the user exactly what they are signing (e.g., "Send 1.5 ETH to 0xabc...").
• Security Isolation: By using a separate domain, it prevents XSS or other vulnerabilities in your application from accessing the user's wallet shards.

Comparison: Customer vs. Organizational Custody

Next Steps

Continue to the Onboarding & PIN Setup guide to learn how to register your first customer.