Overview

PrivateKit is a standalone page served by the auth-central app that is meant to be embedded as an <iframe> inside a third-party host. Unlike Web3Kit (which signs in an end user), PrivateKit operates on behalf of an already-authenticated user and exposes private-area actions over the auth-central /private/api/v1/users endpoints.

The current version supports four action families — change username, change email (with verification), change phone (with verification) and change password — sharing the same message envelope, connectionId discipline, and AUTH_TOKEN_401 semantics. Additional actions can be added with the same shape.

The host owns the UI (the input, the submit button, the validation messages it wants to render). PrivateKit, running inside the iframe, owns the authenticated calls to auth-central and translates API outcomes into a small set of postMessage events.

Architecture

┌──────────────────────────┐    postMessage    ┌──────────────────────────┐
│                          │ ◀──────────────── │                          │
│  Host service            │                   │  PrivateKit (iframe)     │
│  (parent window)         │ ────────────────▶ │  /private-kit            │
│  owns UI + private token │                   │  calls /private/api/...  │
└──────────────────────────┘                   └──────────────────────────┘

Responsibilities

Side	Responsible for
Host (parent)	Collecting the new value (e.g. username) and the user's private authToken; routing inbound messages by connectionId.
Iframe (PrivateKit)	Calling GET /private/api/v1/users, POST /private/api/v1/users/exists, POST /private/api/v1/users/{id}/setUsername, POST /private/api/v1/users/{id}/setEmail, POST /private/api/v1/users/{id}/setPhone, POST /private/api/v1/users/changePassword, POST /private/api/v1/verification/confirm/{id}, POST /private/api/v1/verification/resendEmail/{id}, POST /private/api/v1/verification/resendSms/{id}; mapping API responses to the message contract; detecting 401 and surfacing it as a dedicated event.

Source files in this repo

What	Path
Iframe page	src/pages/PrivateKitPage/PrivateKitPage.tsx
Reference consumer (demo)	src/pages/DemoPrivateKitTestPage/DemoPrivateKitTestPage.tsx
Exported enums (the contract)	src/pages/PrivateKitPage/PrivateKitPage.tsx (named exports)
Underlying Account API client	src/modules/Account/apiService/apiClient.ts
Shared validation	src/helpers/validations.ts (userNameValidation)

A live demo is available in this repo at /demo → sign in → on the success page click Test private kit.

Differences from Web3Kit

Aspect	Web3Kit	PrivateKit
User state	Anonymous — signing in	Already authenticated
authToken location	Embedded in the iframe URL (/oauth/<token>/…)	Sent in the message payload of every action (UPDATE_USERNAME)
Backend API namespace	/web3/*	/private/api/v1/users/*
Mounted at	/oauth/<authToken>/web3-kit	/private-kit (token-less URL)

Because the private authToken is short-lived, PrivateKit explicitly surfaces a 401 outcome (AUTH_TOKEN_401) so the host can trigger a refresh and retry instead of treating the failure as a generic error.