50 KiB
50 KiB
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
- Tenant Registration Flow
- Login Flows
- SSO Configuration Flow
- MCP Token Management Flow
- User Stories
- 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.
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.comas 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 | 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
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:
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:
- Loading: Show spinner with "Completing sign-in..."
- Success: Brief success message + redirect to dashboard
- 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
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
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
-
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
-
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
-
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
-
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
-
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"
-
Suspended Account
- Detection: Check user.status on login
- Message: "Your account has been suspended. Contact support for assistance."
- Action: Block login
- Recovery: Support ticket
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
Slow API Response (>3s)
- UI: Show loading skeleton
- Message: "Loading..."
- Timeout: 30s, then show error
- Recovery: Retry button
-
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
-
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:
- Review with product team
- Create UI mockups based on these flows
- Implement frontend components
- Conduct usability testing
Questions or Feedback: Contact UX/UI team at ux@colaflow.com