Web Service Onboarding Skill

The Core Pattern

CODEBLOCK0

Do this in a single unbroken browser session. Never close the browser between steps.

Critical Rules (Learned the Hard Way — Turnkey, 2026-03-25)

1. One session, no gaps

• - Complete signup AND API key creation AND secret storage in the same browser session
• Close the browser only after credentials are saved to 1Password
• If the browser closes before credentials are extracted, you've lost access — the passkey/session is gone

2. Email alias trap

• - Proton Mail (and many providers) treat user+alias@domain.com as the same user
• If the service already has an account for user@domain.com, the alias will route to that existing account
• Always check whether the service resolves aliases before using them for a fresh account
• Use a completely different email (different domain, different provider) for a truly separate account

3. WebAuthn virtual authenticator is ephemeral

• - Playwright's WebAuthn.addVirtualAuthenticator creates an in-memory credential store
• The passkey it registers is only valid for that browser process
• If you close the browser and reopen it, the credential is gone forever
• The only way to reuse it is to export the credential before closing, then re-import on next run
• Export immediately after registration:

  const creds = await cdp.send('WebAuthn.getCredentials', { authenticatorId });
  fs.writeFileSync('/tmp/webauthn-creds.json', JSON.stringify(creds));
  

• - Re-import on next session:

4. Email verification is link-based, not always OTP

• - Don't assume OTP input fields — check the actual email body first
• Turnkey, Vercel, Railway, Render all send magic links not codes
• Parse the email body with quoted-printable decoding before extracting URLs
• Watch for soft line breaks (=\n) in QP-encoded emails

5. Session cookies are tied to the authenticator

• - If you complete signup in context A and try to use the session in context B, it won't work
• Cookies + passkey credential must stay in the same browser context

6. Internal APIs are not public APIs

• - app.service.com/internal/api/* endpoints require session cookies
• INLINECODE5 endpoints require API key stamping
• You can't call public API endpoints to bootstrap if you have no API key yet
• Only the internal API (cookie-auth) is accessible from an authenticated browser session

Workflow

Phase A: Send signup email (clean context — no cookies)

Why separate? Prevents existing session cookies from hijacking the signup flow.

Phase B: Complete signup + save API keys (same context throughout)

const ctx = await browser.newContext({ storageState: undefined });
const page = await ctx.newPage();
const cdp = await ctx.newCDPSession(page);

// Set up virtual authenticator BEFORE navigating
await cdp.send('WebAuthn.enable', { enableUI: false });
const { authenticatorId } = await cdp.send('WebAuthn.addVirtualAuthenticator', {
  options: {
    protocol: 'ctap2', transport: 'internal',
    hasResidentKey: true, hasUserVerification: true,
    isUserVerified: true, automaticPresenceSimulation: true,
  }
});

// Navigate to verify link
await page.goto(verifyUrl);

// Complete signup steps...

// IMMEDIATELY export credential after passkey registration
const creds = await cdp.send('WebAuthn.getCredentials', { authenticatorId });
fs.writeFileSync('/tmp/webauthn-creds.json', JSON.stringify(creds));
console.log('Credentials backed up:', creds.credentials?.length);

// Continue to API key + wallet creation IN SAME SESSION
// ...save API keys...

// Close browser ONLY after saving everything to 1Password

Email Fetching via Proton Bridge IMAP

CODEBLOCK5

Key: Pattern-match the redirect URL to the service's domain, not a generic URL.

Proton Mail Setup

• - IMAP host: 127.0.0.1, port: 1143, STARTTLS
• Credentials in 1Password: INLINECODE8
• Bridge must be running: INLINECODE9

Input/Form Filling — Use Native Value Setter

Standard element.fill() sometimes fails on React inputs. Use this:

CODEBLOCK6

Button Clicking — Scroll Into View First

Buttons outside viewport fail with element is outside of the viewport. Always scroll:

CODEBLOCK7

After Successful Authentication — save API keys

For services with internal browser APIs:

// Call authenticated internal API from page context
const data = await page.evaluate(async () => {
  const r = await fetch('/internal/api/v1/whoami');
  return r.json();
});
// data.organizationId, data.userId, etc.

Creating API Keys / Resources via Internal API

Once authenticated (cookie present), call internal endpoints from the page context:

CODEBLOCK9

Important: Internal endpoints vary per service. Before creating resources, capture network traffic to learn the real endpoint:

page.on('request', req => {
  if (req.method() !== 'GET' && req.url().includes(serviceDomain))
    console.log(req.method(), req.url());
});

Saving to 1Password

CODEBLOCK11

Signup Registry (MANDATORY)

Before starting any signup, add an entry to the Notion signup registry:

• - DB: INLINECODE12
• Fields: service name, email used, date, purpose
• This is non-negotiable per POLICIES.md

Service-Specific Notes

Turnkey (app.turnkey.com)

• - Email verify: link-based (magic link, not OTP)
• Auth: WebAuthn passkey (virtual authenticator works)
• Post-signup API: /tkhq/api/v1/activities (internal, cookie-auth)
• Public API: api.turnkey.com/public/v1/ requires X-Stamp (signed request)
• Email aliases (+tag) map to the same Turnkey account — use a different provider for separate orgs
• Org created in one run: b7378687-cf82-45ab-a46c-7dda9239001d (Reddi Agent Protocol)

Generic patterns

• - Vercel: email OTP or GitHub OAuth
• Railway: GitHub OAuth (no email signup)
• Supabase: email + password, then API key in dashboard
• Fly.io: email + credit card, CLI bootstrap preferred

Pre-flight Checklist

Before starting any signup:

• - [ ] Added to Notion signup registry
• [ ] Confirmed email available (not already used for this service)
• [ ] Email aliases: does service collapse them? (test first)
• [ ] IMAP readable for email provider being used
• [ ] 1Password vault accessible
• [ ] Proton Bridge running (if using Proton)
• [ ] Sufficient budget for paid tier (if applicable) — ask Nissan first