Embedded WaaS

​

Why Turnkey for Embedded WaaS?

​

Core Principles

• Segregated environments per end user: Each end user’s wallets, credentials, policies, and activity logs are fully isolated from other users and from your platform’s management layer.
• Configurable admin and billing controls: For every fund-moving transaction, you can require approval from both the end user and your platform, enforced directly at the signing layer.
• User-authenticated action: No transaction executes without the end user’s authentication (e.g., passkey).
• Non-custodial by design: End users remain in control of their keys, while platform controls allow you to manage transaction-level approvals.
• User-controlled key export: End users can export their wallet independently if they choose to leave, or if your platform goes offline.
• Quorum control: 2-of-2 root quorum ensures billing, compliance, and risk controls are enforced at the cryptographic layer, while guaranteeing explicit user consent on every transaction.

​

Architecture

​

Transaction Authorization Flow

• End user initiates a transaction from your embedded wallet UI.
• End user approves via their authenticator (e.g., passkey). Turnkey records the activity as partially approved.
• Your platform evaluates on its own backend: billing status, risk/compliance rules, and any other checks.
• Your platform approves via API key and the transaction executes.
• If the platform withholds approval, the transaction does not execute.

​

How to Get Started on Embedded WaaS with Turnkey

​

Step 1: Define the Tenant Model and Ownership Boundaries

• Isolated tenants: Each sub-org is a self-contained data boundary, with wallets, policies, authenticators, and activity logs fully isolated from one another.
• Scoped parent org permissions: Your parent organization has read-only access to sub-orgs and can initiate auth and recovery flows, but cannot sign transactions or modify policies within them.
• External mapping: Track the relationship between your platform’s user IDs and their corresponding Turnkey sub-org IDs in your own database.

​

Step 2: Design the Sub-Organization Control Model

• End user (root): Authenticated via passkey or equivalent user-controlled authenticator.
• WaaS provider (root): Authenticated via API key. Used to approve or block transactions based on your service rules.
• Delegated Access (optional): If needed for automation or backend-initiated workflows, add a scoped non-root API key via Delegated Access. DA must be tightly policy-scoped and should never have broad signing authority or bypass user consent.

​

Step 3: Define Default Wallet and Policy Template

const subOrg = await turnkeyClient.createSubOrganization({
  parameters: {
    subOrganizationName: `User Wallet - ${userId}`,
    rootUsers: [
      { userName: "Platform", apiKeys: [{ publicKey: PROVIDER_KEY }] },
      {
        userName: "End User",
        authenticators: [
          {
            /* passkey */
          },
        ],
      },
    ],
    rootQuorumThreshold: 1,
    wallet: {
      walletName: "Primary Wallet",
      accounts: [
        {
          /* eth account */
        },
      ],
    },
  },
});

await turnkeyClient.createPolicy({
  organizationId: subOrgId,
  parameters: {
    policyName: "Allow User Wallet Export",
    effect: "EFFECT_ALLOW",
    consensus: `approvers.any(user, user.id == '${endUserId}')`,
    condition: `activity.type == 'ACTIVITY_TYPE_EXPORT_WALLET'
      && wallet.id == '${walletId}'`,
  },
});

await turnkeyClient.updateRootQuorum({
  organizationId: subOrgId,
  parameters: {
    threshold: 2,
    userIds: [providerUserId, endUserId],
  },
});

​

Step 4: Build the Developer-Facing SDK or Integration Surface

• Embedded Wallet Kit (EWK): Fork or wrap Embedded Wallet Kit components (e.g., authentication, wallet UI, and approval prompts) with your branding and surface “pending platform approval” states.
• Backend service: Handle platform root approvals (via API key), billing and risk evaluation, and activity monitoring through your backend.
• SDK abstraction layer: Wrap Turnkey’s SDK calls behind your own interface for full control over the developer experience, with flexibility to swap or upgrade infrastructure without breaking integrations.

​

Step 5: Incorporate the Embedded Wallet into the Platform Flow

• Onboarding: Handle Turnkey org setup, auth configuration, and the staged sub-org creation flow as part of your user registration. The end user should experience passkey registration (or equivalent) as a natural part of sign-up.
• Client initialization: Initialize the Turnkey client with the user’s sub-org context on each session. Use sessions for batched signing workflows to reduce authentication friction during active use.
• Transaction flow: Surface the approval prompt via EWK components, submit the user’s approval to Turnkey, run your backend checks, then co-sign or withhold.
• Recovery: Expose the export flow in your settings UI so users can self-serve wallet recovery. Turnkey’s enclave encrypts the mnemonic to a user-generated target key via HPKE. Neither Turnkey nor your platform can view the exported material.

​

Use Cases

​

The Result: Non-Custodial Control at the Infrastructure Layer

• Tenant isolation: Isolated user wallets, credentials, and activity logs help protect end users’ key material and data.
• Quorum control: 2-of-2 root quorum guarantees explicit user consent on every transaction.
• Flexible models: Customers can evolve custody models over time as needs change.
• Full auditability: Every operation is logged and nothing moves unless both the user and your platform approve.

​

DIMO Case Study

• Passkey-first onboarding: DIMO replaced seed phrases and external wallet installs with Turnkey’s passkey authentication, cutting sign-in time from 2 minutes to 10 seconds and boosting onboarding completion by 30%.
• Fully branded interface: DIMO built a native auth and signing experience on an open-source transactions SDK, powered by Turnkey’s Embedded WaaS passkey-based signing.
• Sub-org per user with full ownership: Each driver gets an independent sub-organization, giving them complete control of their credentials and transactions while DIMO retains the governance layer needed for enterprise compliance.
• 2-3 week integration: DIMO deployed into their global login stack in under three weeks.

​

Resources

• Sub-organizations: Tenant isolation and user modeling
• Root quorum: Multi-party approval and ownership configuration
• Policy engine: Authorization rules, transaction controls, and export policies
• Embedded Wallet Kit: Prebuilt UI components for auth and wallet flows
• Export wallets: Key export and user recovery