Identity for your AI agent.

"Authenticate alice@home.com via email."

Sends a magic link to alice@home.com. Anyone who opens it authenticates as their own Wink account (alice's mailbox and Wink-account emails may differ — keeps the flow forgiving).

email:

alice@home.com

lock_to_email:

(omitted)

"Authenticate alice@home.com by sending a link locked to this email."

Same delivery, but WinkKey enforces that the user completing the flow has alice@home.com on their Wink account. Anyone else gets user_mismatch.

email:

alice@home.com

lock_to_email:

alice@home.com

"Email a sign-in link to ops@team.com but only allow alex@acme.com to complete."

Delivery and identity addresses diverge. The team inbox receives the message; only Alex's Wink account can pass the user_mismatch check at completion.

email:

ops@team.com

lock_to_email:

alex@acme.com

"Enroll me with Wink — set up a new Wink account."

In-room enrollment. QR + URL render inline; user scans with their phone, completes face capture and profile. The agent calls request_enrollment FIRST — no auth step in front of it. Active session is recorded on completion, so subsequent profile/wallet ops in the same turn need no rid.

1. 1.request_enrollment() → rid + enroll_url + QR
2. 2.wait_for_biometric_auth(rid) → {kind: 'enroll', winktag, …}
3. 3.get_user_profile() → confirm what the new user picked

"Invite alice@acme.com to Wink."

Remote new-user onboarding. SendGrid emails the link; recipient opens it on their own device, completes enrollment. TTL defaults to 48 hours since recipients often delay acting on enrollment emails. Loop the wait — emails are read on human time.

1. 1.send_enrollment_email({email: alice@acme.com}) → rid + sent_to
2. 2.wait_for_biometric_auth(rid) → {kind: 'enroll', …} // loop on timeout

"Sign up bob@example.com — lock the new Wink account to that email and brand the screen 'Welcome to Acme'."

Identity-locked enrollment with a branded screen. lock_to_email pre-binds the new Wink account to bob@example.com so he can't pick a different email mid-flow. display_title / display_subtext customize WinkKey's heading and subtitle (also available on the auth pair).

1. 1.send_enrollment_email({email: bob@example.com, lock_to_email: bob@example.com, display_title: 'Welcome to Acme', display_subtext: 'Quick face setup, then youre in'}) → rid
2. 2.wait_for_biometric_auth(rid) → {kind: 'enroll', …}

"Wait, I sent that to the wrong email — cancel it and resend to alice@correct.com."

Cancellation works for both auth and enroll links. The cancelled rid moves to status='failed' on WinkKey, so any wait_for_biometric_auth still in flight resolves to a terminal state instead of stalling for the full TTL. Same tool also covers 'I sent the auth link to the wrong inbox' — works regardless of kind.

1. 1.send_enrollment_email({email: alice@wrong.com}) → rid_old
2. 2.cancel_biometric_auth({request_id: rid_old}) → {ok, status: 'failed'}
3. 3.send_enrollment_email({email: alice@correct.com}) → rid_new
4. 4.wait_for_biometric_auth(rid_new) → {kind: 'enroll', …}

"Authenticate me with Wink and show my saved cards."

The user is at the same device as the agent. QR + URL render inline; user scans / clicks; cards come back automatically. Notice get_user_cards omits request_id — the server falls back to the just-completed session.

1. 1.request_biometric_auth() → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.get_user_cards() → cards // rid reused from active session

"Email a sign-in link to alice@home.com and list her cards once she completes."

Remote user. Magic link goes to alice's inbox; agent blocks on the wait, then fetches cards using the auth event's vaulted token. Open delivery — alice authenticates as herself on her own device.

1. 1.send_biometric_auth_email({email: alice@home.com}) → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.get_user_cards() → cards

"Ping jordan@example.com for their cards."

Same shape as 'via email' but the user phrasing is informal. The mobile router still picks send_biometric_auth_email because of the email + identity-fetch intent. Loops on wait_for_biometric_auth if the user takes longer than 55s.

1. 1.send_biometric_auth_email({email: jordan@example.com}) → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.get_user_cards() → cards

"Authenticate alice@home.com via email and pull her default shipping address and a card to charge."

Same auth front-end as the email flow above, but the agent fans out to both wallet endpoints once auth is consumed. Both reads omit request_id — they reuse the same active session, no extra arg threading needed.

1. 1.send_biometric_auth_email({email: alice@home.com}) → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.get_user_addresses() → addresses
4. 4.get_user_cards() → cards

"Build a checkout for alice@home.com — $42.50 for a coffee subscription."

Physical product (default kind), fixed price. The named recipient routes the agent to prepare_email_checkout (email is required there). Passkey path allowed — fastest UX for users with one set up.

1. 1.prepare_email_checkout({email: alice@home.com, kind: physical, product_label: 'coffee subscription', amount_cents: 4250}) → checkout_id
2. 2.wait_for_checkout(checkout_id) → {status: confirmed, amount, card, address}

"Build a high-security checkout for alice@home.com — $1,200 for a watch. Force wink cloud."

User-requested ceremony. force_wink_cloud=true suppresses the passkey button on WinkKey's verify screen, routing the buyer through a full Wink cloud sign-in. Both paths produce a valid session — this flag is purely a UX preference for high-trust ceremony, not a requirement for downstream wallet calls. Triggered by phrases like 'force wink cloud', 'no passkeys', 'enforce wink auth', 'high-security checkout'.

1. 1.prepare_email_checkout({email: alice@home.com, amount_cents: 120000, force_wink_cloud: true}) → checkout_id
2. 2.wait_for_checkout(checkout_id) → {status: confirmed, …}

"Build me a checkout for $15 — digital. Show me the QR."

In-room flow. No email mentioned → agent picks prepare_inline_checkout (no email arg at all, eliminating the model's habit of asking for one). kind='digital' hides the shipping picker. Returns URL + a QR image content block — rendered inline by Claude Desktop, surfaced as a link by ChatGPT.

1. 1.prepare_inline_checkout({kind: digital, amount_cents: 1500}) → {auth_url, qr_url} + QR image
2. 2.wait_for_checkout(checkout_id) → {status: confirmed, amount, card}

"Save a shipping address for me — Alex Kim, 999 Oak Ave, Austin TX 78701."

Agent collects the fields conversationally and posts in one call. Phone backfilled from the user's Wink profile. Returns the new address_id which subsequent get_user_addresses + prepare_email_checkout pick up automatically.

1. 1.request_biometric_auth() → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.add_user_address({full_name, line1, …, type: shipping}) → {address_id}

"Build a $25 checkout for me, physical."

On the page, uncheck 'Use my billing for shipping' → form appears → fill it → leave 'Save to my Wink profile' checked → Confirm. The server saves the address to Wink (server-to-server) before recording the checkout intent. The address shows up in your wallet for next time.

1. 1.prepare_inline_checkout({kind: physical, amount_cents: 2500}) → checkout_id
2. 2.<page form: address fields + save_address: true>
3. 3.wait_for_checkout(checkout_id) → {status: confirmed, amount, card, address}

"Update my shipping to 100 New St — replace the old Austin one."

Wink has no PUT/PATCH for addresses, so 'edit' is add-new + delete-old. Agent runs both tools in sequence; both omit request_id (active session reused).

1. 1.add_user_address({…new fields…, type: shipping}) → {address_id: NEW}
2. 2.delete_user_address({address_id: OLD}) → {ok: true}

"What's on my Wink profile?"

Pulls the shaped {winktag, first_name, last_name, email, phone} plus raw_profile (the full body Wink returned). The raw passthrough is a debug aid for when Wink renames a field between deployments and the shaped view comes back null.

1. 1.request_biometric_auth() → rid
2. 2.wait_for_biometric_auth(rid) → identity
3. 3.get_user_profile() → {profile, raw_profile}

"Change my Wink email to alice@new.com and update my phone too."

Sparse PUT — only the fields the agent passes get written. The server reads the profile back after the write and returns the fresh state in the same response, so the agent confirms what landed without a separate get_user_profile call.

1. 1.update_user_profile({email: alice@new.com, phone: '+1...'}) → {ok, updated_fields, profile}

"Send me a Wink PIN so I can complete checkout on my laptop."

Wink generates the PIN and emails it to the user's profile address. The MCP server discards Wink's response body (which contains the PIN) and returns only {ok, sent_to: <email>}. The agent tells the user to check their inbox; nobody in the chat surface ever sees the digits.

1. 1.generate_winkpin() → {ok: true, sent_to: 'a***@example.com'}

"Does +1 415 555 1212 already have a Wink account?"

Merchant-level check — no biometric auth required. Useful as a pre-flight before send_biometric_auth_email so the agent can phrase the prompt as 'sign in' vs 'create an account'. Returns {exists, raw}; raw is exposed when Wink's response shape isn't recognized so the agent can fall back gracefully.

1. 1.validate_contact_no({phone: '+14155551212'}) → {exists: true}