# Multi-Tenant UX Flows

## Document Overview

This document defines the user experience flows for multi-tenant functionality, SSO integration, and MCP Token management in ColaFlow. It includes user journeys, interaction patterns, and edge case handling.

**Version:** 1.0
**Last Updated:** 2025-11-03
**Owner:** UX/UI Team

---

## Table of Contents

1. [Tenant Registration Flow](#tenant-registration-flow)
2. [Login Flows](#login-flows)
3. [SSO Configuration Flow](#sso-configuration-flow)
4. [MCP Token Management Flow](#mcp-token-management-flow)
5. [User Stories](#user-stories)
6. [Edge Cases and Error Handling](#edge-cases-and-error-handling)

---

## Tenant Registration Flow

### User Journey: New Company Signs Up

**Goal:** Create a new tenant (company) and first admin account in one seamless flow.

```mermaid
flowchart TD
    A[User visits colaflow.com] --> B[Clicks 'Start Free Trial']
    B --> C[Step 1: Company Info]
    C --> D{Slug Available?}
    D -->|Yes| E[Step 2: Admin Account]
    D -->|No| F[Show Error + Suggest Alternatives]
    F --> C
    E --> G[Step 3: Choose Plan]
    G --> H{Submit Registration}
    H --> I[Create Tenant + Admin User]
    I --> J[Send Verification Email]
    J --> K[Redirect to acme.colaflow.com/onboarding]
    K --> L[Show Welcome Tour]
```

### Step-by-Step Breakdown

#### Step 1: Company Information

**URL:** `/signup?step=1`

**Fields:**
- Company Name (text, required)
  - Validation: 2-100 characters
  - Example: "Acme Corporation"
- Company Slug (text, required, unique)
  - Validation: 3-50 characters, lowercase, alphanumeric + hyphens
  - Real-time availability check (debounced 500ms)
  - Preview: Shows `acme.colaflow.com` as user types
  - Suggest alternatives if taken: `acme-corp`, `acme-team`, `acme2`

**UI Elements:**
- Progress indicator: `● ○ ○` (Step 1 of 3)
- "Company Slug" has info tooltip: "This will be your custom ColaFlow URL"
- Live preview badge showing the full domain
- Green checkmark or red X for availability status

**Validation Messages:**
- Empty: "Company name is required"
- Too short: "Company name must be at least 2 characters"
- Slug taken: "This URL is already taken. Try: acme-corp, acme-team"
- Invalid characters: "Slug can only contain lowercase letters, numbers, and hyphens"
- Reserved: "This name is reserved. Please choose another"

**Next Button:** Enabled only when both fields are valid and slug is available.

---

#### Step 2: Administrator Account

**URL:** `/signup?step=2`

**Fields:**
- Full Name (text, required)
  - Validation: 2-100 characters
- Email Address (email, required)
  - Validation: Valid email format
  - Check: Not already registered
- Password (password, required)
  - Validation: 8+ characters, uppercase, lowercase, number, special char
  - Real-time strength indicator (Weak / Medium / Strong)
- Confirm Password (password, required)
  - Must match password field

**UI Elements:**
- Progress indicator: `✓ ● ○` (Step 2 of 3)
- Password strength bar (red → yellow → green)
- Password requirements checklist:
  - ☑ At least 8 characters
  - ☑ One uppercase letter
  - ☑ One lowercase letter
  - ☑ One number
  - ☑ One special character
- "Show/Hide password" toggle

**Validation Messages:**
- Email already exists: "This email is already registered. Try logging in instead?"
- Passwords don't match: "Passwords must match"
- Weak password: "Password is too weak. Add more complexity"

---

#### Step 3: Choose Subscription Plan

**URL:** `/signup?step=3`

**Plan Options:**

| Feature | Free | Starter ($19/mo) | Professional ($49/mo) | Enterprise (Custom) |
|---------|------|------------------|----------------------|---------------------|
| Users | 5 | 15 | 50 | Unlimited |
| Projects | 3 | 20 | 100 | Unlimited |
| Storage | 2 GB | 10 GB | 100 GB | 1 TB |
| SSO | ✗ | ✗ | ✓ | ✓ |
| MCP Tokens | 3 | 10 | 50 | Unlimited |
| Support | Community | Email | Priority | Dedicated |

**UI Elements:**
- Progress indicator: `✓ ✓ ●` (Step 3 of 3)
- Plan cards with highlighted "Most Popular" badge on Professional
- "Start with Free" / "Start with Starter" buttons
- "What's included" expandable sections
- Comparison table toggle
- Payment method NOT required for Free plan

**Interaction:**
- Clicking a plan highlights it
- "Continue" button shows plan name: "Continue with Free Plan"
- For paid plans: Note "14-day free trial, no credit card required"

**Final Step:**
- Checkbox: "I agree to the Terms of Service and Privacy Policy"
- Large "Create Account" button
- Processing state: "Creating your workspace..."
- Success animation + redirect to `acme.colaflow.com/onboarding`

---

### Success State

**Welcome Screen:**
```
┌──────────────────────────────────────────┐
│  🎉 Welcome to ColaFlow, Acme Corp!      │
│                                          │
│  Your workspace is ready:                │
│  🌐 acme.colaflow.com                    │
│                                          │
│  Next steps:                             │
│  1. Invite your team members             │
│  2. Create your first project            │
│  3. Configure integrations               │
│                                          │
│  [Skip Tour]  [Start Quick Tour]         │
└──────────────────────────────────────────┘
```

---

## Login Flows

### Flow 1: Local Login (Email + Password)

**URL:** `acme.colaflow.com/login`

```mermaid
flowchart TD
    A[User visits acme.colaflow.com/login] --> B[Tenant Resolved from Subdomain]
    B --> C{SSO Configured?}
    C -->|No| D[Show Email + Password Form Only]
    C -->|Yes| E[Show SSO Buttons + OR + Local Form]
    D --> F[User Enters Credentials]
    E --> G{User Chooses Login Method}
    G -->|Local| F
    G -->|SSO| H[Redirect to IdP]
    F --> I[Validate Credentials]
    I -->|Success| J[Generate JWT]
    I -->|Failure| K[Show Error: Invalid credentials]
    J --> L[Redirect to /dashboard]
    K --> F
```

**Local Login UI:**

```
┌──────────────────────────────────────────┐
│         Welcome to Acme Corp             │
│                                          │
│  Email Address                           │
│  [user@acme.com              ]           │
│                                          │
│  Password                                │
│  [******************] [👁]               │
│                                          │
│  [☐] Remember me                         │
│  Forgot password?                        │
│                                          │
│  [Sign In →]                             │
└──────────────────────────────────────────┘
```

---

### Flow 2: SSO Login (Azure AD / Google / Okta)

**URL:** `acme.colaflow.com/login` (when SSO is configured)

**SSO-Enabled UI:**

```
┌──────────────────────────────────────────┐
│         Welcome to Acme Corp             │
│                                          │
│  [🟦 Continue with Microsoft]            │
│  [🔴 Continue with Google]               │
│                                          │
│  ──────────── OR ────────────            │
│                                          │
│  Sign in with your email                 │
│  Email Address                           │
│  [user@acme.com              ]           │
│                                          │
│  Password                                │
│  [******************] [👁]               │
│                                          │
│  [Sign In →]                             │
└──────────────────────────────────────────┘
```

**SSO Flow:**

```mermaid
sequenceDiagram
    participant U as User
    participant FE as ColaFlow Frontend
    participant API as ColaFlow API
    participant IdP as Identity Provider (Azure AD)
    participant DB as Database

    U->>FE: Clicks "Continue with Microsoft"
    FE->>API: POST /api/auth/sso/initiate (provider: AzureAD)
    API->>DB: Load tenant SSO config
    DB-->>API: SSO Configuration
    API->>API: Generate state token (CSRF protection)
    API-->>FE: Redirect URL + state
    FE->>IdP: Redirect with OAuth params
    IdP->>U: Show Microsoft login page
    U->>IdP: Enter corporate credentials
    IdP->>API: Callback with authorization code
    API->>IdP: Exchange code for tokens
    IdP-->>API: ID Token + Access Token
    API->>API: Validate ID Token signature
    API->>DB: Find or create user (auto-provision)
    DB-->>API: User entity
    API->>API: Generate JWT with tenant claims
    API-->>FE: Set JWT in HTTP-only cookie
    FE->>FE: Store user info in state
    FE->>U: Redirect to /dashboard
```

**SSO Loading State:**

```
┌──────────────────────────────────────────┐
│                                          │
│         Authenticating with              │
│            Microsoft...                  │
│                                          │
│            [Spinner Animation]           │
│                                          │
│  Please complete sign-in in the popup    │
│                                          │
└──────────────────────────────────────────┘
```

---

### Flow 3: SSO Callback

**URL:** `/auth/sso/callback?code=xxx&state=yyy`

**States:**

1. **Loading:** Show spinner with "Completing sign-in..."
2. **Success:** Brief success message + redirect to dashboard
3. **Error:** Show error with "Back to Login" button

**Error Messages:**
- "Authentication failed: Invalid state parameter" (CSRF)
- "Authentication failed: Email domain not allowed"
- "Authentication failed: User account suspended"
- "Authentication failed: SSO session expired"

---

## SSO Configuration Flow

### User Journey: Admin Configures SSO

**Role:** Tenant Administrator
**Goal:** Enable SSO for company users

```mermaid
flowchart TD
    A[Admin navigates to Settings] --> B[Click 'Single Sign-On']
    B --> C[See empty state / current config]
    C --> D[Click 'Configure SSO']
    D --> E[Select SSO Provider]
    E --> F{Provider Type}
    F -->|OIDC| G[Enter Authority, Client ID, Secret]
    F -->|SAML| H[Enter Entity ID, SSO URL, Certificate]
    G --> I[Configure Auto-Provisioning]
    H --> I
    I --> J[Add Allowed Email Domains]
    J --> K[Click 'Test Connection']
    K --> L{Test Result}
    L -->|Success| M[Show Success Message]
    L -->|Failure| N[Show Error Details]
    N --> G
    M --> O[Click 'Save Configuration']
    O --> P[SSO Enabled Successfully]
    P --> Q[Show confirmation + instructions]
```

### Empty State

**URL:** `/settings/sso`

```
┌────────────────────────────────────────────────┐
│  Single Sign-On (SSO)                          │
├────────────────────────────────────────────────┤
│                                                │
│          🔐                                    │
│                                                │
│   Enable enterprise SSO for your team          │
│                                                │
│   SSO allows your team to log in with their    │
│   corporate credentials (Azure AD, Google,     │
│   Okta, or SAML 2.0).                          │
│                                                │
│   ✓ Centralized access control                 │
│   ✓ No need to remember passwords             │
│   ✓ Automatic user provisioning               │
│                                                │
│   [Configure SSO]                              │
│                                                │
│   ℹ️ Available for Professional and Enterprise │
│     plans only                                 │
└────────────────────────────────────────────────┘
```

---

### SSO Configuration Form

**Tabs:** General | OIDC Config | SAML Config | Users | Test

#### Tab 1: General

```
Provider *
[Azure AD ▼]
  - Azure AD / Microsoft Entra
  - Google Workspace
  - Okta
  - Generic SAML 2.0

Auto-Provision Users
[✓] Automatically create accounts for new users

Require Email Verification
[☐] Require users to verify email after SSO login

Allowed Email Domains (Optional)
[@acme.com          ] [+ Add]
[@acme.co.uk        ] [🗑️]

Restriction: Only users with these email domains can log in via SSO.
Leave empty to allow all domains.
```

#### Tab 2: OIDC Config (for Azure AD, Google, Okta)

```
Authority / Issuer URL *
[https://login.microsoftonline.com/tenant-id]
ℹ️ For Azure AD: Get this from Azure Portal → App Registrations

Client ID *
[xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx]
ℹ️ Your application's Client ID from the IdP

Client Secret *
[********************] [Show]
ℹ️ Keep this secret secure. It will be encrypted in our database.

Metadata URL (Optional)
[https://login.microsoftonline.com/.well-known/openid-configuration]
ℹ️ Auto-discovery endpoint for OIDC metadata

Callback URL (Read-only)
[https://acme.colaflow.com/api/auth/sso/callback]
ℹ️ Configure this URL in your IdP's allowed redirect URIs
[Copy]
```

**Provider-Specific Help:**

- **Azure AD:** Link to "How to register an app in Azure AD"
- **Google:** Link to "Google Cloud Console setup guide"
- **Okta:** Link to "Okta application setup guide"

#### Tab 3: SAML Config (for Generic SAML)

```
Entity ID *
[https://idp.acme.com/saml]
ℹ️ Your IdP's entity identifier

Single Sign-On URL *
[https://idp.acme.com/sso]
ℹ️ The IdP endpoint where SAML authentication requests are sent

X.509 Certificate *
[-----BEGIN CERTIFICATE-----
MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcN...
-----END CERTIFICATE-----         ]

ℹ️ IdP's public certificate for signature verification.
Paste the full certificate including BEGIN/END lines.

Metadata URL (Optional)
[https://idp.acme.com/metadata.xml]
ℹ️ If provided, we'll automatically fetch IdP metadata

Service Provider Metadata (Read-only)
[https://acme.colaflow.com/api/auth/sso/saml/metadata]
ℹ️ Provide this URL to your IdP for automatic configuration
[Copy] [Download XML]
```

#### Tab 4: Users

Show list of users who have logged in via SSO:

```
SSO Users (12)

[Search users...]

┌─────────────────────────────────────────────────────────┐
│ Name              Email              Last Login  Status  │
├─────────────────────────────────────────────────────────┤
│ John Doe         john@acme.com      2 hours ago  Active │
│ Jane Smith       jane@acme.com      1 day ago    Active │
│ Bob Johnson      bob@acme.com       Never        Pending│
└─────────────────────────────────────────────────────────┘

Auto-provisioned: 10
Manually created: 2
```

#### Tab 5: Test Connection

```
Test SSO Configuration

Before enabling SSO for your team, verify that your
configuration is correct.

[Test Connection]

Test Results:
┌─────────────────────────────────────────────────────────┐
│ ✓ Metadata endpoint reachable                           │
│ ✓ OIDC discovery document valid                         │
│ ✓ Certificate signature valid                           │
│ ✓ Callback URL whitelisted                              │
│                                                          │
│ Status: All checks passed ✓                             │
└─────────────────────────────────────────────────────────┘

[< Back]  [Save Configuration]
```

**Test Failure Example:**

```
Test Results:
┌─────────────────────────────────────────────────────────┐
│ ✓ Metadata endpoint reachable                           │
│ ✗ Failed to validate client secret                      │
│   Error: Invalid client credentials                     │
│                                                          │
│ Status: Configuration has errors ✗                      │
│                                                          │
│ Troubleshooting:                                        │
│ 1. Verify your Client ID and Secret in Azure Portal     │
│ 2. Ensure the application has correct permissions       │
│ 3. Check that the callback URL is whitelisted           │
└─────────────────────────────────────────────────────────┘

[< Back to Configuration]
```

---

### Success State

After saving SSO configuration:

```
┌────────────────────────────────────────────────┐
│  ✓ SSO Configuration Saved                     │
├────────────────────────────────────────────────┤
│                                                │
│  Azure AD SSO is now enabled for Acme Corp.    │
│                                                │
│  Your team can now log in using their          │
│  @acme.com Microsoft accounts.                 │
│                                                │
│  Next steps:                                   │
│  1. Test SSO login with your account           │
│  2. Share login URL with your team:            │
│     https://acme.colaflow.com/login            │
│  3. Disable local passwords (optional)         │
│                                                │
│  [Test SSO Login]  [Invite Team]               │
└────────────────────────────────────────────────┘
```

---

## MCP Token Management Flow

### User Journey: Generate MCP Token for AI Agent

**Role:** Any authorized user
**Goal:** Create an MCP token for Claude Desktop / ChatGPT integration

```mermaid
flowchart TD
    A[User navigates to Settings → MCP Tokens] --> B{Has Tokens?}
    B -->|No| C[Show Empty State]
    B -->|Yes| D[Show Token List]
    C --> E[Click 'Generate Token']
    D --> E
    E --> F[Step 1: Token Info]
    F --> G[Step 2: Configure Permissions]
    G --> H[Step 3: Review & Create]
    H --> I[Token Generated]
    I --> J[Display Token ONE TIME ONLY]
    J --> K{User Action}
    K -->|Copy| L[Token Copied to Clipboard]
    K -->|Download| M[Download .env File]
    L --> N[User Confirms 'I've saved it']
    M --> N
    N --> O[Token Hidden Forever]
    O --> P[Show in Token List]
```

### Empty State

**URL:** `/settings/mcp-tokens`

```
┌────────────────────────────────────────────────┐
│  MCP API Tokens                                │
├────────────────────────────────────────────────┤
│                                                │
│          🤖                                    │
│                                                │
│   Connect AI agents to ColaFlow                │
│                                                │
│   MCP Tokens allow AI assistants like Claude   │
│   and ChatGPT to access your projects, create  │
│   tasks, and generate reports on your behalf.  │
│                                                │
│   ✓ Fine-grained permissions                   │
│   ✓ Revocable at any time                     │
│   ✓ Full audit trail                          │
│                                                │
│   [Generate Your First Token]                  │
│                                                │
│   📖 Learn more about MCP integration          │
└────────────────────────────────────────────────┘
```

---

### Token List View

```
┌────────────────────────────────────────────────────────────────┐
│  MCP API Tokens                                                │
│                                                                │
│  [+ Generate New Token]                      [Filter: All ▼]   │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  Active Tokens (3)                                             │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ Claude Desktop                                            │ │
│  │ Permissions: Projects (R), Issues (R/W), Documents (R)    │ │
│  │ Created: 2025-11-01 • Last Used: 2 hours ago             │ │
│  │ Expires: In 30 days                                       │ │
│  │                                                           │ │
│  │ [View Details]  [Revoke]                                  │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ ChatGPT Assistant                                         │ │
│  │ Permissions: Projects (R), Issues (R), Reports (R)        │ │
│  │ Created: 2025-10-20 • Last Used: Yesterday                │ │
│  │ Expires: In 60 days                                       │ │
│  │                                                           │ │
│  │ [View Details]  [Revoke]                                  │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  ┌──────────────────────────────────────────────────────────┐ │
│  │ CI/CD Pipeline                                            │ │
│  │ Permissions: Issues (C/U), Sprints (R)                    │ │
│  │ Created: 2025-10-15 • Last Used: Never                    │ │
│  │ Expires: Never                                            │ │
│  │                                                           │ │
│  │ [View Details]  [Revoke]                                  │ │
│  └──────────────────────────────────────────────────────────┘ │
│                                                                │
│  Revoked Tokens (1) [Show]                                     │
└────────────────────────────────────────────────────────────────┘
```

---

### Token Generation Modal

#### Step 1: Token Information

```
┌────────────────────────────────────────────────┐
│  Generate New MCP Token                 [× ]  │
├────────────────────────────────────────────────┤
│  Step 1 of 3: Token Information         ● ○ ○ │
│                                                │
│  Token Name *                                  │
│  [Claude Desktop                     ]         │
│  ℹ️ A friendly name to identify this token     │
│                                                │
│  Description (Optional)                        │
│  [Used for my personal AI assistant   ]        │
│  [that helps manage my tasks          ]        │
│                                                │
│  Expiration                                    │
│  [◉] 30 days                                   │
│  [○] 60 days                                   │
│  [○] 90 days                                   │
│  [○] Never (Enterprise only)                   │
│                                                │
│  ℹ️ You can revoke this token at any time      │
│                                                │
│                      [Cancel]  [Next →]        │
└────────────────────────────────────────────────┘
```

#### Step 2: Configure Permissions

**Option A: Template-Based**

```
┌────────────────────────────────────────────────┐
│  Generate New MCP Token                 [× ]  │
├────────────────────────────────────────────────┤
│  Step 2 of 3: Permissions               ○ ● ○ │
│                                                │
│  Choose a Permission Template                  │
│                                                │
│  [◉] Read Only (Recommended)                   │
│      View projects, issues, and documents.     │
│      Cannot make changes.                      │
│                                                │
│  [○] Read + Write                              │
│      View and create issues/documents.         │
│      Cannot delete.                            │
│                                                │
│  [○] Custom                                    │
│      Define specific permissions below.        │
│                                                │
│  ──────────────────────────────────────────    │
│                                                │
│  Advanced Options (Optional)                   │
│                                                │
│  Require Approval For:                         │
│  [☐] Issue status changes                      │
│  [☐] Document publishing                       │
│  [☐] Project archiving                         │
│                                                │
│  ℹ️ AI will submit changes for human review    │
│                                                │
│                     [← Back]  [Next →]         │
└────────────────────────────────────────────────┘
```

**Option B: Permission Matrix (if Custom selected)**

```
┌─────────────────────────────────────────────────────┐
│  Generate New MCP Token                      [× ]  │
├─────────────────────────────────────────────────────┤
│  Step 2 of 3: Custom Permissions            ○ ● ○ │
│                                                     │
│  Select permissions for each resource type:         │
│                                                     │
│  Resource    │ Read │Create│Update│Delete│Search   │
│  ───────────┼──────┼──────┼──────┼──────┼────────  │
│  Projects    │  ✓   │      │      │      │   ✓     │
│  Issues      │  ✓   │  ✓   │  ✓   │      │   ✓     │
│  Documents   │  ✓   │  ✓   │      │      │   ✓     │
│  Reports     │  ✓   │      │      │      │         │
│  Sprints     │  ✓   │      │      │      │   ✓     │
│  Comments    │  ✓   │  ✓   │      │      │         │
│                                                     │
│  ⚠️ Delete permissions are restricted for safety    │
│                                                     │
│  Selected: 13 permissions                           │
│                                                     │
│                        [← Back]  [Next →]           │
└─────────────────────────────────────────────────────┘
```

#### Step 3: Review & Create

```
┌────────────────────────────────────────────────┐
│  Generate New MCP Token                 [× ]  │
├────────────────────────────────────────────────┤
│  Step 3 of 3: Review                    ○ ○ ● │
│                                                │
│  Review Your Token Configuration               │
│                                                │
│  Name: Claude Desktop                          │
│  Description: Used for my personal AI...       │
│  Expires: In 30 days (2025-12-03)              │
│                                                │
│  Permissions:                                  │
│    Projects: Read, Search                      │
│    Issues: Read, Create, Update, Search        │
│    Documents: Read, Create, Search             │
│    Reports: Read                               │
│                                                │
│  Restrictions:                                 │
│    Issue status changes require approval       │
│                                                │
│  ℹ️ You'll see the token only once after       │
│     creation. Make sure to copy and save it.   │
│                                                │
│                     [← Back]  [Create Token]   │
└────────────────────────────────────────────────┘
```

---

### Token Display (One-Time Only)

```
┌─────────────────────────────────────────────────────┐
│  ✓ Token Created Successfully!           [× ]      │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ⚠️ IMPORTANT: Save this token now!                 │
│                                                     │
│  This is the ONLY time you'll see this token.       │
│  If you lose it, you'll need to generate a new one. │
│                                                     │
│  Your Token:                                        │
│  ┌─────────────────────────────────────────────┐   │
│  │ mcp_acme_7f3d8a9c4e1b2f5a6d8c9e0f1a2b3c4d  │   │
│  └─────────────────────────────────────────────┘   │
│  [📋 Copy to Clipboard]                             │
│                                                     │
│  ──────────────────────────────────────────────    │
│                                                     │
│  How to Use This Token:                             │
│                                                     │
│  1. Copy the token above                            │
│  2. Add it to your AI assistant's configuration:    │
│     - Claude Desktop: Settings → MCP Servers        │
│     - ChatGPT: Custom GPT configuration             │
│  3. Set as environment variable:                    │
│     COLAFLOW_MCP_TOKEN=mcp_acme_xxx...              │
│                                                     │
│  [Download as .env file]                            │
│                                                     │
│  ──────────────────────────────────────────────    │
│                                                     │
│  [☐] I have saved this token securely               │
│                                                     │
│  [Close]                                            │
└─────────────────────────────────────────────────────┘
```

**Interaction:**
- "Copy to Clipboard" button shows success toast: "Token copied!"
- "Download as .env file" downloads a file named `colaflow-mcp-token.env`:
  ```
  # ColaFlow MCP Token
  # Token Name: Claude Desktop
  # Created: 2025-11-03
  # Expires: 2025-12-03

  COLAFLOW_MCP_TOKEN=mcp_acme_7f3d8a9c4e1b2f5a6d8c9e0f1a2b3c4d
  ```
- Checkbox must be checked to enable "Close" button
- Closing without checking shows confirmation: "Are you sure? You won't be able to see this token again."

---

### Token Details Page

**URL:** `/settings/mcp-tokens/[tokenId]`

```
┌─────────────────────────────────────────────────────┐
│  [← Back to Tokens]                                 │
│                                                     │
│  Claude Desktop                            [Active] │
│  Created on November 1, 2025                        │
├─────────────────────────────────────────────────────┤
│                                                     │
│  📋 Token Information                               │
│                                                     │
│  Name: Claude Desktop                               │
│  Description: Used for my personal AI assistant     │
│  Created: 2025-11-01 10:30 AM                       │
│  Last Used: 2 hours ago (2025-11-03 08:15 AM)       │
│  Expires: In 27 days (2025-12-01)                   │
│  Status: Active                                     │
│  Usage Count: 1,247 requests                        │
│                                                     │
│  🔐 Permissions                                     │
│                                                     │
│  Projects                                           │
│    ✓ Read    ✗ Create    ✗ Update    ✗ Delete      │
│                                                     │
│  Issues                                             │
│    ✓ Read    ✓ Create    ✓ Update    ✗ Delete      │
│                                                     │
│  Documents                                          │
│    ✓ Read    ✓ Create    ✗ Update    ✗ Delete      │
│                                                     │
│  Reports                                            │
│    ✓ Read    ✗ Create    ✗ Update    ✗ Delete      │
│                                                     │
│  📊 Recent Activity (Last 7 Days)                   │
│                                                     │
│  Chart: [Activity line graph showing API calls]     │
│                                                     │
│  📝 Audit Log                                       │
│  [Showing last 50 operations]                       │
│                                                     │
│  Timestamp           Action      Resource   Result  │
│  ─────────────────  ──────────  ─────────  ───────  │
│  2025-11-03 08:15   Read        Issue #123  Success │
│  2025-11-03 08:10   Create      Issue #456  Success │
│  2025-11-03 08:05   Update      Issue #456  Success │
│  2025-11-03 08:00   Read        Project #1  Success │
│  2025-11-03 07:55   Search      Issues      Success │
│  ...                                                │
│                                                     │
│  [Load More]                                        │
│                                                     │
│  ⚠️ Danger Zone                                     │
│                                                     │
│  [Revoke This Token]                                │
│  Once revoked, this token will stop working         │
│  immediately. This action cannot be undone.         │
│                                                     │
└─────────────────────────────────────────────────────┘
```

**Revoke Confirmation:**

```
┌────────────────────────────────────────────────┐
│  Revoke Token?                                 │
├────────────────────────────────────────────────┤
│                                                │
│  Are you sure you want to revoke this token?   │
│                                                │
│  Token: Claude Desktop                         │
│  Last used: 2 hours ago                        │
│                                                │
│  This will:                                    │
│  • Immediately stop all API access             │
│  • Cannot be undone                            │
│  • You'll need to generate a new token         │
│                                                │
│  Reason for Revocation (Optional)              │
│  [No longer needed                   ]         │
│                                                │
│                   [Cancel]  [Revoke Token]     │
└────────────────────────────────────────────────┘
```

---

## User Stories

### Story 1: First-Time Company Registration

**As a** startup founder
**I want to** quickly sign up for ColaFlow with my company
**So that** I can start managing my projects immediately

**Acceptance Criteria:**
- Can complete registration in under 2 minutes
- Company slug is validated in real-time
- Password requirements are clear
- Can choose a plan without entering payment info
- Receive a welcome email with next steps

---

### Story 2: SSO Login for Enterprise User

**As an** enterprise employee
**I want to** log in with my corporate Microsoft account
**So that** I don't need to remember another password

**Acceptance Criteria:**
- SSO button is prominently displayed on login page
- Login flow completes in under 10 seconds
- My profile info (name, email, avatar) is auto-populated
- I'm automatically added to my company's workspace
- I can still use local login if SSO fails

---

### Story 3: Admin Configures SSO

**As a** company administrator
**I want to** configure Azure AD SSO for my team
**So that** everyone can log in with their corporate accounts

**Acceptance Criteria:**
- Step-by-step wizard with clear instructions
- Can test connection before saving
- Provider-specific help documentation available
- Can restrict SSO to specific email domains
- Can auto-provision users on first login

---

### Story 4: Developer Creates MCP Token for Claude

**As a** developer
**I want to** create an MCP token for my Claude Desktop app
**So that** Claude can help me manage tasks automatically

**Acceptance Criteria:**
- Can generate token in under 1 minute
- Permission templates make setup easy
- Token is displayed only once with clear warning
- Can copy token or download .env file
- Instructions for Claude Desktop setup included

---

### Story 5: User Reviews Token Activity

**As a** security-conscious user
**I want to** see all API activity for my MCP tokens
**So that** I can verify there's no unauthorized access

**Acceptance Criteria:**
- Can view detailed audit log for each token
- Can see usage charts and statistics
- Can quickly identify unusual activity
- Can revoke token immediately if needed
- Revocation takes effect instantly

---

## Edge Cases and Error Handling

### Registration Edge Cases

1. **Slug Already Taken**
   - **Detection:** Real-time check on blur/debounced typing
   - **Message:** "This URL is already taken. Try: acme-corp, acme-team, acme2"
   - **Action:** Suggest 3 alternatives
   - **Recovery:** User can edit slug field

2. **Email Already Registered**
   - **Detection:** On submit (Step 2)
   - **Message:** "This email is already registered. Try logging in instead? [Log In]"
   - **Action:** Offer direct link to login page
   - **Recovery:** User can use different email

3. **Network Failure During Registration**
   - **Detection:** Timeout or connection error
   - **Message:** "Connection lost. Your progress is saved. [Retry]"
   - **Action:** Save form state in session storage
   - **Recovery:** Restore form on retry

4. **Reserved Slug**
   - **Detection:** Real-time validation
   - **Message:** "This name is reserved. Please choose another."
   - **List:** www, api, admin, app, dashboard, docs, blog, support
   - **Recovery:** User must choose different slug

---

### Login Edge Cases

1. **Wrong Password (3+ Attempts)**
   - **Detection:** Track failed attempts per user
   - **Message:** "Too many failed attempts. Your account is temporarily locked for 15 minutes."
   - **Action:** Throttle login attempts
   - **Recovery:** Wait or use "Forgot Password"

2. **Suspended Account**
   - **Detection:** Check user.status on login
   - **Message:** "Your account has been suspended. Contact support for assistance."
   - **Action:** Block login
   - **Recovery:** Support ticket

3. **SSO Misconfiguration**
   - **Detection:** SSO flow fails
   - **Message:** "SSO login is currently unavailable. Use your email and password instead."
   - **Action:** Fall back to local login
   - **Recovery:** Admin fixes SSO config

4. **Email Domain Not Allowed (SSO)**
   - **Detection:** After IdP callback
   - **Message:** "Your email domain (@external.com) is not allowed for SSO. Contact your administrator."
   - **Action:** Reject login
   - **Recovery:** Admin adds domain to allowed list

5. **Expired SSO Session**
   - **Detection:** IdP returns error
   - **Message:** "Your SSO session has expired. Please log in again."
   - **Action:** Redirect to login
   - **Recovery:** User retries login

---

### SSO Configuration Edge Cases

1. **Invalid Client Secret**
   - **Detection:** Test connection fails
   - **Message:** "Failed to authenticate with IdP: Invalid client credentials"
   - **Troubleshooting:**
     - Verify Client ID and Secret in IdP portal
     - Check application permissions
     - Ensure redirect URIs are correct
   - **Recovery:** User corrects credentials

2. **Certificate Parse Error (SAML)**
   - **Detection:** Certificate validation fails
   - **Message:** "Invalid X.509 certificate format. Ensure you've copied the full certificate including BEGIN/END markers."
   - **Action:** Show certificate format example
   - **Recovery:** User pastes correct certificate

3. **Callback URL Not Whitelisted**
   - **Detection:** IdP returns redirect_uri_mismatch
   - **Message:** "Callback URL not whitelisted in IdP. Add https://acme.colaflow.com/api/auth/sso/callback to allowed redirect URIs."
   - **Action:** Show copy button for callback URL
   - **Recovery:** User updates IdP config

4. **SSO Enabled But No Users Can Log In**
   - **Detection:** Email domain restrictions too strict
   - **Message:** "Warning: No users match your allowed domains. Add @acme.com to allow your team."
   - **Action:** Suggest adding domains
   - **Recovery:** Admin adds domains

---

### MCP Token Edge Cases

1. **Token Generation Fails**
   - **Detection:** Server error on create
   - **Message:** "Failed to generate token. Please try again. If the problem persists, contact support."
   - **Action:** Log error
   - **Recovery:** User retries

2. **User Closes Modal Without Saving Token**
   - **Detection:** User clicks [X] or clicks outside
   - **Message:** "Are you sure? You won't be able to see this token again."
   - **Action:** Show confirmation dialog
   - **Recovery:** User can go back or confirm closure

3. **User Tries to View Token Again**
   - **Detection:** User clicks on token in list
   - **Message:** "For security, tokens cannot be viewed after creation. Generate a new token if needed."
   - **Action:** Show token details but not the actual token
   - **Recovery:** User generates new token

4. **Token Expired But Still in Use**
   - **Detection:** API call with expired token
   - **Message:** (To AI agent) "Token expired. Please regenerate."
   - **Action:** Return 401 Unauthorized
   - **Recovery:** User generates new token

5. **Revoke Token That's Actively Being Used**
   - **Detection:** Usage detected in last 5 minutes
   - **Message:** "This token was used 3 minutes ago. Revoking will immediately stop all access. Continue?"
   - **Action:** Show extra confirmation
   - **Recovery:** User confirms or cancels

6. **Zero Permissions Selected**
   - **Detection:** Form validation on Step 2
   - **Message:** "You must select at least one permission for this token."
   - **Action:** Highlight permissions section
   - **Recovery:** User selects permissions

7. **Attempt to Delete Resource (Forbidden)**
   - **Detection:** API permission check
   - **Message:** (To AI agent) "Permission denied: Token does not have delete permission for issues."
   - **Action:** Log attempt in audit log
   - **Recovery:** User grants delete permission if needed

---

### Network and Performance Edge Cases

1. **Slow API Response (>3s)**
   - **UI:** Show loading skeleton
   - **Message:** "Loading..."
   - **Timeout:** 30s, then show error
   - **Recovery:** Retry button

2. **Offline Mode**
   - **Detection:** navigator.onLine = false
   - **Message:** "You're offline. Some features may not work."
   - **Action:** Show banner at top
   - **Recovery:** Auto-hide when online

3. **Session Expired**
   - **Detection:** 401 from API
   - **Message:** "Your session has expired. Please log in again."
   - **Action:** Redirect to login with return URL
   - **Recovery:** User logs in again

---

## Animation and Timing Guidelines

### Micro-interactions

- **Button Hover:** 150ms ease-out
- **Input Focus:** 200ms ease-in-out
- **Tooltip Appear:** 300ms ease-out with 500ms delay
- **Toast Notification:** 300ms slide-in, auto-dismiss after 4s

### Page Transitions

- **Route Change:** 300ms fade-in
- **Modal Open:** 300ms scale-in + fade-in
- **Modal Close:** 200ms scale-out + fade-out
- **Drawer Open:** 300ms slide-in
- **Accordion Expand:** 300ms ease-out

### Loading States

- **Button Loading:** Show spinner immediately, min 500ms
- **Page Loading:** Show skeleton after 200ms
- **API Call:** Show spinner after 500ms (hide for fast responses)

---

## Conclusion

This UX flow document provides comprehensive guidance for implementing multi-tenant, SSO, and MCP token management features. All flows prioritize security, clarity, and user control while maintaining a seamless experience.

**Next Steps:**
1. Review with product team
2. Create UI mockups based on these flows
3. Implement frontend components
4. Conduct usability testing

**Questions or Feedback:** Contact UX/UI team at ux@colaflow.com
