{"slug":"developers/ONBOARDING_API_CONTRACT","title":"Onboarding API Contract — IntegrateWise Unified Platform","section":"developers","sectionLabel":"Developers","status":"unclassified","type":"document","path":"developers/ONBOARDING_API_CONTRACT.mdx","bytes":4799,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Endpoints\n\n### POST /api/onboarding/start\n\n- Body: `{ email, name, picture, oauthProvider, oauthSub }`\n- Returns: `{ userId, tenantId, onboardingToken, status: \"in_progress\" }`\n- Action: Creates user + tenant (owner role), issues JWT\n\n### POST /api/onboarding/step/:stepNumber\n\n- stepNumber: 0-6\n- Body: step-specific payload\n- Returns: `{ success, nextStep, committedFields, status }`\n- Each step progressively commits to `tenant_spine_config`\n\n#### Step 0 — Usage Type\n\nBody: `{ usageType: \"personal\" | \"work\" | \"business\" }`\nCommits: `tenant_spine_config.user_type`\n\n#### Step 1 — Industry\n\nBody: `{ industry: string }` — one of 11 + \"Other\"\nCommits: `tenant_spine_config.industry`, starts progressive hydration\n\n#### Step 2 — Department / Role\n\nBody: `{ department: string, subRole: string }`\nDepartment: one of 12 (Sales, Marketing, RevOps, CS, Support, Eng, Product, Finance, Legal, HR, Supply Chain, Service Ops)\nSubRole: department-scoped\nCommits: `tenant_spine_config.department`, `tenant_spine_config.sub_role`, derives `enabled_entities`, `north_star_metric`\n\n#### Step 3 — Company Size\n\nBody: `{ companySize: \"1-10\" | \"11-50\" | \"51-200\" | \"201-500\" | \"501-1k\" | \"1k-5k\" | \"5k+\" }`\nCommits: `tenant_spine_config.company_size`, sets connector quotas + sync cadence defaults\n\n#### Step 4 — Connectors\n\nBody: `{ connectors: [{ id, provider, type, config? }] }`\nTypes: \"continuity_bridge\" (required), \"storage\", \"mcp\", \"ai_provider\", \"native\"\nCommits: connector records, triggers Nango OAuth redirects\n\n#### Step 5 — Desired Outcome\n\nBody: `{ primaryGoal: string }` — organize | insights | context | team | automate | docs\nCommits: personalization flags, first AI insight config\n\n#### Step 6 — Workspace Name\n\nBody: `{ workspaceName: string }`\nCommits: Final `tenant_spine_config` write, marks onboarding complete, triggers spine hydration\n\n### POST /api/onboarding/complete\n\n- Body: `{ onboardingToken }`\n- Returns: `{ success, redirectUrl, dashboardUrl }`\n- Action: Finalizes RBAC, hydrates Spine projection, triggers first sync\n\n### GET /api/tenant-spine-config\n\n- Headers: `Authorization: Bearer <jwt>`\n- Returns: Full `tenant_spine_config` row + derived persona projection\n\n## D1 Schema\n\n```sql\nCREATE TABLE IF NOT EXISTS onboarding_sessions (\n  id TEXT PRIMARY KEY,\n  user_id TEXT NOT NULL,\n  tenant_id TEXT NOT NULL,\n  status TEXT DEFAULT 'in_progress', -- in_progress | completed | abandoned\n  current_step INTEGER DEFAULT 0,\n  completed_steps TEXT, -- JSON array of step numbers\n  payload TEXT, -- JSON object of all captured fields\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE TABLE IF NOT EXISTS tenant_spine_config (\n  tenant_id TEXT PRIMARY KEY,\n  industry TEXT,\n  department TEXT,\n  sub_role TEXT,\n  user_type TEXT,\n  company_size TEXT,\n  enabled_entities TEXT, -- JSON array\n  north_star_metric TEXT,\n  schema_version TEXT DEFAULT 'v2.0',\n  governance_posture TEXT, -- JSON object\n  twin_greeting_id TEXT,\n  onboarding_complete INTEGER DEFAULT 0,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,\n  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE TABLE IF NOT EXISTS rbac_users (\n  user_id TEXT PRIMARY KEY,\n  tenant_id TEXT NOT NULL,\n  role_id TEXT NOT NULL,\n  level TEXT,\n  scope TEXT,\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE TABLE IF NOT EXISTS rbac_roles (\n  role_id TEXT PRIMARY KEY,\n  tenant_id TEXT NOT NULL,\n  name TEXT,\n  capabilities TEXT, -- JSON array\n  inherits TEXT, -- JSON array\n  created_at DATETIME DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE TABLE IF NOT EXISTS rbac_permissions (\n  perm_id TEXT PRIMARY KEY,\n  name TEXT,\n  scope TEXT,\n  gate_posture TEXT\n);\n```\n\n## Persona Matrix (12 × 11)\n\nStored as JSON configuration in `packages/config/persona-matrix.json`:\n\n- 12 departments with CTX enums, entity vocabularies, KPI sets, Twin greetings\n- 11 industries with base resource types, compliance flags, vertical connectors\n- 132 cross-product schema variants (derived at runtime, not stored)\n\n## Frontend → Backend Flow\n\n1. Marketplace OAuth callback → frontend receives identity token\n2. Frontend calls `/api/onboarding/start` with OAuth claims\n3. Frontend renders 7-step wizard, calling `/api/onboarding/step/:n` at each step\n4. Step 4 triggers Nango OAuth popups for each selected connector\n5. Step 6 calls `/api/onboarding/complete` → triggers hydration → redirects to dashboard\n6. Dashboard reads `/api/tenant-spine-config` to render persona-shaped projection\n"}