# Third-party onboarding (UF/T0–T4)

> Level-3 reference for [skill.md](../skill.md). Fetch: `https://cai.com/skill-references/onboarding.md`

## Third-party sites: registration & login custody (product scope)

**What CAI does:** Help users connect **catalog third-party platforms** (`platform_id` from `platforms_supported_list`) **and** **arbitrary official HTTPS third-party sites** (hosted browser onboarding + **site vault** by `origin_host`). Store **replayable** login-related credentials in the **vault** (server-side encrypted) so later agent sessions can reuse them via API tools — **without** putting passwords or long-lived secrets in chat.

**What this skill does *not* guarantee as the same tier:** Running every **in-site** product action (place trade, publish content, game moves, etc.) — those depend on per-platform connectors or future scope; the **default promise here is registration/bind + credential retention + connector-based “who am I / balance / profile” style calls**, not “full remote control of the website UI.”

**Default onboarding identity:** Prefer the user’s **@cai.com** email and **CAI custodial main wallet** when the target platform allows. Use another person’s wallet or external WalletConnect (`link_subwallet`, etc.) **only** if the user **explicitly** asks.

### Unified third-party onboarding — UF/T0–T4 model

**Core principle (§0 North Star):** Automate registration/binding wherever possible via **T0/T1/T2** (programmatic connector, OAuth redirect, API key on secure page). Fall back to **official URL + user confirmation** only when automation is not feasible. **`create_website_login_link`** is a **legacy optional handoff** — not the primary registration path.

**Credential tiers:**

| Tier | Name | What CAI stores |
|------|------|-----------------|
| **T0** | Programmatic connector / wallet-derive | `wallet_bound`, connector output |
| **T1** | OAuth → CAI redirect | `oauth_token` |
| **T2** | API key / PAT on secure page | `api_key` |
| **T3** | Hosted page + user-obtained secret | metadata only |
| **T4** | Pure browser session | **nothing** — honest limits |

**User-Facing flows:** Classify to route correctly:

| Flow | When | Primary action |
|------|------|----------------|
| **UF-1** | Web2 email/password signup | Programmatic API or T2; `website_login` only as fallback |
| **UF-2** | Web3 / DEX (wallet + signature) | T0 `platform_one_click_register` or app WalletConnect; **not** email-password |
| **UF-3** | OAuth-only sites | T1 OAuth via `redirect_uri` back to CAI |
| **UF-4** | Not automatable (CAPTCHA, SSO, invite-only) | **Honest stop**: explain limits; `human_verification` or official URL |

**OpenClaw / MCP hosts:** Assume **`CAI_API_KEY`** with sufficient scope ( **`mail`** or **`full`** for §5 mailbox tools; **`platform`** / **`full`** for vault / one-click; **`pay`** / **`full`** for transfers). Optionally **`CAI_USER_JWT`** to force a browser session for the same routes. Third-party onboarding uses the same HTTP tools as other agents; there is no separate “OpenClaw-only” API. **Wallet-derive / one-click** may still need **`private_key`** or **cai.com app / website.html** signing until custodial gateway signing ships — state that honestly; do not ask for **`private_key`** in chat when avoidable (prefer app flows).

**Do not** add **per-site** top-level skill routing (no special decision-table row per brand). The same **Discovery → identify registration path → classify → execute** procedure applies for every third-party register/bind request (see [WEBSITE_ONBOARDING_SPEC.md](../docs/register_login_website_v2/WEBSITE_ONBOARDING_SPEC.md) §0.3, §15.1). **No** document or eval table should **hardcode** verdicts for specific hostnames as permanent product rules — catalog rows and validator output change over time.

**Mandatory procedure:** For **any** “register / bind / connect” intent on a third-party site (URL pasted or name only):

1. **Normalize:** Resolve an official **`https://`** origin or hostname; confirm with the user if ambiguous.
2. **Discovery (capability scan — not an allowlist check):** Call **`platforms_supported_list`** with a **narrow query** (`q` = hostname or slug fragment) when you have a host. Optionally call **`POST /uars-profile-site`** with `{ "url": "<official https or host>" }` for a single JSON profile (`one_click_first`, `recommended_flow`, `hitl_official_urls`) when the orchestrator benefits from a structured summary. Read **`connector_configured`**, **`connection_approach`**, **`registration_hint`**, **`auth_type`**. **Empty or no match** means **no prebuilt programmatic connector row** for that host — **not** “CAI cannot talk about the site,” but also **not** “we can auto-register.”
3. **Identify registration path (required):** From Discovery + user intent, state **how** this service expects signup (email, wallet, OAuth, API key issuance, invite-only, etc.). Use **`registration_hint`** and connector metadata **first**; if unknown, follow **UF-4 / W10** — ask for official URL or screenshot — **do not** guess. **Admin-only** `platforms-validate-and-add-discovery` results (Gate 1/2) are **not** callable by API-key agents; never pretend you ran them unless the product exposed a user tool.
4. **Classify:** Map the target to **UF-1–UF-4** and Tier (Web3 / DEX → UF-2; heavy gates → UF-4; etc.).
5. **Execute:** Call tools that match the **identified** path; tell the user **why** each step exists.

**When registration cannot be automated (honest stop — no `website_login` fake-out):** If Discovery + hints show **`connector_configured === false`** for programmatic bind, or **`registration_hint` / connector docs** imply **browser-only signup**, **manual API key copy**, or **no server-side registration API**, you **must** say clearly that CAI **cannot** complete registration on the user’s behalf through the API, and that **`create_website_login_link` is not an adequate substitute**: CAI **does not** read third-party httpOnly cookies; **most** targets **block** embedding (CSP); the hosted **`/act` `website_login`** page uses **new-tab-first** when needed, a **copyable @cai.com** line, **two acknowledgements** (used CAI email on the third-party site → completed official human/verification steps), then “record to CAI”; when a **`registration_run_id`** is attached, **`registration_run_user_ack`** runs (JWT) so progress is auditable — it still **does not** capture tokens for **relogin** or vault by itself. **Do not** mint **`create_website_login_link`** as the **default** response to “register me” in that situation. Instead: give the **official HTTPS URL** in prose, recommend **@cai.com** when email signup is relevant (JWT mail / OTP per §5), and **`vault_save_site_credential`** (or platform vault + secure UI) **only after** the user obtains a **replayable** secret themselves — **never** imply the hosted page alone registered or saved login.

**Programmatic-bind-first when Discovery hits F-16:** If step 2 matches a catalog row by **slug**, **name**, or **hostname** from **`base_url` / pasted URL**, and that row has **`connector_configured === true`** and **`connection_approach`** in **`wallet_derive`**, **`api_key_manual`**, **`openapi_or_doc`**, **`skill_or_mcp`**, and the user wants **register / bind / connect**, you **MUST** attempt **`platform_one_click_register`** (or the row’s **`register_doc`** path) **before** any hosted third-party browser handoff. **Do not** mint **`create_website_login_link`** as the **first** tool call in that situation.

**After** `platform_one_click_register` fails with a **specific** backend code that means “complete something on the official site first” (e.g. **`OFFICIAL_PROFILE_REQUIRED`**, legacy **`POLYMARKET_PROFILE_REQUIRED`**), or when **CAPTCHA** is required: explain the blocker; prefer **`create_human_verification_link`** when the user must complete a **known** human step, or plain **official URL + steps** in chat. **`create_website_login_link`** remains a **legacy / optional** handoff — use **only** when the user **explicitly** wants the CAI-hosted chrome and understands it **does not** populate vault or relogin by itself.

**Catalog path (summary):**

1. **`platform_id` matched:** Programmatic row + **`connector_configured`** → **`platform_one_click_register`** first → vault on success. **`platform_get_user_data`** when vault + connector support it.
2. **No `platform_id` match:** **Do not** refuse solely because the site is absent from the list. **Do not** call **`platform_one_click_register`** without a **`platform_id`**. Classify UF; if registration is **not** automatable, use the **honest stop** paragraph above (official URL, @cai.com guidance, vault **after** user-supplied secrets). **Web3 / DEX** → UF-2 (wallet / signature), not forced email-password narrative.

**All paths:** CAI **does not** read third-party **httpOnly cookies** or copy arbitrary browser sessions into the agent.

**Honesty:** **API-key agents** need scope **`mail`** or **`full`** to use §5 **@cai.com** mailbox tools; **`read`** alone is not enough. OAuth, SMS, CAPTCHA, and regional gates may still need human or app steps. Do not claim **100% instant** registration for every URL.

**Roadmap (documented, not assumed live):** User-facing **`site_signup_capability_probe`** or equivalent, deeper email/OAuth automation, custodial gateway signing — ship per product; until then follow the steps above.

**Data model note:** **Catalog vault** (`user_platform_credentials`) is keyed by **`platform_id`**. **Site vault** (`user_site_credentials`) keys **normalized `origin_host`**. Prefer **`platform_id`** + `vault_save_platform_credential` when the site is on the catalog; use **site vault** when the user brings a **replayable** secret for an arbitrary origin. Same encryption env: **`PLATFORM_CREDENTIALS_ENCRYPTION_KEY`**.

**“Remember my login” (user wording):** Treat as saving **replayable credentials** (T0–T2: connector / one-click output, OAuth tokens returned to CAI, API keys via the **secure page**) — **not** capturing the user’s **browser session** or **httpOnly cookies** from `website_login`. If they only have a pure web session with no API, state **T4** limits honestly. Canonical narrative: [docs/register_login_website_v2/WEBSITE_ONBOARDING_SPEC.md](../docs/register_login_website_v2/WEBSITE_ONBOARDING_SPEC.md) §2.

---