---
name: spinwheel-connect
description: Helps engineers integrate Spinwheel Connect end-to-end, including connect method selection (SMS, KBA, network token, preverified), secure vs standard API host usage, OTP/KBA lifecycle handling, and fallback/error strategy. Use this skill whenever the user mentions Spinwheel Connect, user linking, user authentication for Spinwheel APIs, SMS verification, KBA verification, preverified flows, or asks how to obtain a Spinwheel `userId` before Profile or Pay work.
---

# Spinwheel Connect Integration

Use this skill to guide implementation planning and troubleshooting for Spinwheel user connection flows.

## Outcome

Produce an integration-ready response that includes:
1. Recommended connect strategy for the scenario.
2. Step-by-step API workflow with required identifiers.
3. Error/fallback handling plan.
4. Sandbox-to-production readiness checklist.

## Workflow

### 1) Confirm integration context

Collect the minimum context:
- Environment (`sandbox` or `production`).
- Available user inputs (phone, DOB, identity data).
- Whether the user already has an internal external identifier (`extUserId`).
- Whether preverified or network token integrations are enabled by Spinwheel.

If context is missing, proceed with the SMS-first default and explicitly state assumptions.

### 2) Choose the connect path

Use this decision order:
1. **SMS** as default when a US mobile number and DOB are available.
2. **KBA** when SMS eligibility or identification fails.
3. **Network token** for partner-to-partner interoperability where token flow is available.
4. **Preverified user profile** only when Spinwheel support has enabled it.

### 3) Map the API sequence

Provide the concrete path sequence for the chosen method.

**SMS sequence**
- `POST /v1/users/connect/sms`
- `POST /v1/users/{userId}/connect/sms/verify`

**KBA sequence**
- `POST /v1/users/connect/kba` on secure host
- `PUT /v1/users/{userId}/connect/kba` to submit answers

**Network token sequence**
- `POST /v1/users/connect/network`

**Preverified profile sequence**
- `POST /v1/users/connect/preverified/userProfile` on secure host

Always call out the expected durable result: `userId` for downstream APIs.

### 4) Add resilient error handling

Always include:
- SMS fallback to KBA when `UNSUPPORTED_NUMBER` or identification errors appear.
- OTP expiry and retry throttling handling.
- KBA expiration handling (restart flow when expired).
- Recovery guidance for rate limits (retry strategy + user messaging).

### 5) Provide handoff guidance

After a successful connection:
- Tell the user to persist `userId` and their own `extUserId` mapping.
- Explain that Profile and Pay workflows start from this identifier.
- Include the next likely endpoint suggestion (for example debt profile request).

## Host and auth guardrails

- Use Bearer auth with Spinwheel API secret key in server-to-server calls.
- Call out host differences when relevant:
  - Standard: `https://sandbox-api.spinwheel.io` and `https://api.spinwheel.io`
  - Secure variants for designated endpoints: `secure-sandbox-api` and `secure-api`
- Never imply that all endpoints use secure hosts; mention secure host use only where docs indicate.

## Response format

Use this structure:

### Recommended flow
### API steps
### Error and fallback handling
### Implementation checklist
### Open assumptions

## Quality bar

- Keep guidance grounded in public Spinwheel docs.
- Distinguish required steps from optional optimizations.
- Prefer concrete implementation actions over product marketing language.