# UJ-001 Onboard, connect, and provision API key

Audience: AI coding agents first.

- Actor + entry point: WordPress administrator; `wp-admin/admin.php?page=international-press-zone#/onboarding`.
- Priority: MUST-HAVE.
- Preconditions: Fresh plugin site. Seed purchasable plans through `GET /v1/onboarding/plans?plugin=international`; create account only through `POST /v1/auth/register` or use seeded credentials from that API.
- Test layer: L2.

## Steps

1. Open onboarding → `Welcome to International Press Zone`, `Get Started`, and `I have an account` render (`admin/src/pages/onboarding.js:173-199`).
2. Activate `I have an account` → login state renders; submit valid credentials → plugin calls `POST /v1/auth/login` and advances to subscribed/checkout flow (`docs/contracts/plugin-client-contract.md:181-188`).
3. Complete PayPal approval → plugin polls `GET /v1/subscriptions/checkout-sessions/{id}` until `retrieved`; returned `api_key` and `license_key` become local plugin credentials (`docs/contracts/plugin-client-contract.md:211-228`).
4. Complete language setup → completion screen renders and later settings load reports API key configured.

## Failure branches

- Auth failure: backend `401` → wizard remains on login and renders backend `error.message` (`docs/contracts/plugin-client-contract.md:181-188`).
- Rate limit: backend `429` → wizard remains actionable only after error; render returned error text. No silent retry.
- Backend unreachable: local proxy returns `502 CONNECTION_FAILED`; render error and preserve entered fields (`docs/contracts/plugin-client-contract.md:161-168`).

## Backend touchpoints

`GET /v1/onboarding/plans?plugin=international`; `POST /v1/auth/login`; `POST /v1/subscriptions/checkout`; `GET /v1/subscriptions/checkout-sessions/{id}`; `POST /v1/sites/register`.