YeboID

Your identity. Your agent. Your address on the Yebo network.

What is YeboID?

YeboID is three things in one:

Component	Description
Identity	Your unique handle (@name.yebo) across all Yebo products
Agent	Your personal AI that learns you and acts on your behalf
Wallet	Your unified balance for all transactions

┌─────────────────────────────────────────────┐
│                  YeboID                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐      │
│  │ Identity│  │  Agent  │  │  Wallet │      │
│  │@name.yebo│ │   🤖    │  │  💰     │      │
│  └─────────┘  └─────────┘  └─────────┘      │
│         │          │            │            │
│         └──────────┼────────────┘            │
│                    ▼                         │
│  ┌─────────────────────────────────────┐    │
│  │         YeboVerify (KYC)            │    │
│  │  Unverified → Basic → Full         │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

Verification Levels

YeboID has three tiers linked to YeboVerify KYC:

Level	Requirements	Unlocks	Limits
Unverified	Phone only	Browse, chat, save items	Can't transact
Basic	Phone + ID photo	Buy, sell, receive payments	KES 50k/month
Full	Basic + selfie match + address	Unlimited transactions, withdrawals, business account	Unlimited

Registration Flow

Step 1: Claim Handle

┌─────────────────────────────────────────┐
│                                         │
│   Claim your Yebo address               │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │ @  │ yourname      │ .yebo │ ✓  │   │
│   └─────────────────────────────────┘   │
│                                         │
│   ✓ Available                           │
│                                         │
│   [ Continue with Phone ]               │
│                                         │
└─────────────────────────────────────────┘

Handle Rules:

• 3-20 characters
• Letters, numbers, underscores only
• Lowercase (auto-converted)
• No reserved words (yebo, admin, support, etc.)
• First come, first served
• Cannot change once claimed

Step 2: Phone Verification

┌─────────────────────────────────────────┐
│                                         │
│   Enter your phone number               │
│                                         │
│   ┌─────────────────────────────────┐   │
│   │ 🇰🇪 +254 │ 712 345 678          │   │
│   └─────────────────────────────────┘   │
│                                         │
│   We'll send you a verification code    │
│   via SMS (powered by YeboLink)         │
│                                         │
│   [ Send Code ]                         │
│                                         │
└─────────────────────────────────────────┘

Step 3: KYC Prompt (When Needed)

User tries to buy/sell → KYC prompt appears:

┌─────────────────────────────────────────┐
│                                         │
│   🔒 Verify to continue                 │
│                                         │
│   To buy and sell on Yebo, we need      │
│   to verify your identity. Takes ~2min. │
│                                         │
│   You'll need:                          │
│   • Government ID (passport, national   │
│     ID, or driver's license)            │
│   • A selfie                            │
│                                         │
│   [ Start Verification ]                │
│   [ Maybe Later ]                       │
│                                         │
└─────────────────────────────────────────┘

YeboVerify Integration

YeboID uses YeboVerify API for all KYC:

Verification Flow

User                    YeboID                  YeboVerify
  │                        │                        │
  │─── Upload ID ─────────▶│                        │
  │                        │─── Verify Document ───▶│
  │                        │                        │
  │                        │◀── Extracted Data ─────│
  │                        │                        │
  │◀── "Name: John Kamau"──│                        │
  │    "Is this correct?"  │                        │
  │                        │                        │
  │─── Yes, confirm ──────▶│                        │
  │                        │─── Store verified ────▶│
  │                        │                        │
  │◀── Basic verified! ────│                        │
  │                        │                        │
  │─── Take selfie ───────▶│                        │
  │                        │─── Face match ────────▶│
  │                        │                        │
  │                        │◀── Match: 94% ─────────│
  │                        │                        │
  │◀── Fully verified! ────│                        │
  │    "Limits unlocked"   │                        │

Basic Verification API

POST /api/verify/basic
{
  "yeboId": "user_123",
  "documentType": "national_id",
  "documentFront": "<base64>",
  "documentBack": "<base64>"
}

Response:
{
  "success": true,
  "verificationId": "ver_abc123",
  "status": "approved",
  "extractedData": {
    "fullName": "John Kamau",
    "dateOfBirth": "1995-03-15",
    "idNumber": "12345678",
    "nationality": "KE"
  }
}

Full Verification API

POST /api/verify/full
{
  "yeboId": "user_123",
  "verificationId": "ver_abc123",
  "selfie": "<base64>",
  "address": {
    "line1": "123 Moi Avenue",
    "city": "Nairobi",
    "country": "KE"
  }
}

Response:
{
  "success": true,
  "status": "approved",
  "faceMatchScore": 0.94,
  "kycLevel": "full"
}

Data Model

Users Table

CREATE TABLE yebo_users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  handle VARCHAR(20) UNIQUE NOT NULL,
  phone VARCHAR(20) UNIQUE NOT NULL,
  phone_verified BOOLEAN DEFAULT FALSE,
  email VARCHAR(255),
  
  -- Profile
  display_name VARCHAR(100),
  avatar_url TEXT,
  bio TEXT,
  country VARCHAR(2),
  
  -- KYC (from YeboVerify)
  kyc_level VARCHAR(20) DEFAULT 'unverified',
  kyc_verified_at TIMESTAMP,
  yeboverify_id VARCHAR(100),
  
  -- Extracted from KYC
  legal_name VARCHAR(200),
  date_of_birth DATE,
  id_number VARCHAR(50),
  
  -- Agent Config
  agent_preferences JSONB DEFAULT '{}',
  agent_enabled BOOLEAN DEFAULT TRUE,
  
  -- Wallet
  wallet_balance DECIMAL(15, 2) DEFAULT 0,
  wallet_currency VARCHAR(3) DEFAULT 'KES',
  
  -- Limits
  monthly_transacted DECIMAL(15, 2) DEFAULT 0,
  monthly_limit DECIMAL(15, 2) DEFAULT 0,
  
  -- Meta
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  last_active_at TIMESTAMP,
  status VARCHAR(20) DEFAULT 'active'
);

Authentication

Login Flow

1. User enters phone number
2. Send OTP via YeboLink SMS
3. User enters OTP
4. Verify OTP
5. Generate session token
6. Return user + token

API Endpoints

Endpoint	Method	Description
/auth/check-handle	POST	Check handle availability
/auth/request-otp	POST	Send OTP to phone
/auth/verify-otp	POST	Verify OTP, login/register
/auth/refresh	POST	Refresh access token
/auth/logout	POST	Invalidate session

Request OTP

POST /api/auth/request-otp
{
  "phone": "+254712345678"
}

Response:
{
  "success": true,
  "expiresIn": 300
}

Verify OTP

POST /api/auth/verify-otp
{
  "phone": "+254712345678",
  "otp": "482916"
}

Response:
{
  "success": true,
  "isNewUser": false,
  "user": {
    "id": "...",
    "handle": "john",
    "displayName": "John Kamau",
    "kycLevel": "basic"
  },
  "accessToken": "eyJ...",
  "refreshToken": "..."
}

Agent Component

Each YeboID has an agent that:

Learns Over Time

• Preferred categories (jobs, products)
• Price ranges
• Communication style
• Active hours

Acts Proactively

• Job matching & auto-apply (if enabled)
• Price drop alerts
• Invoice reminders
• Restock notifications

Preferences Schema

{
  "jobPreferences": {
    "roles": ["ui designer", "product designer"],
    "locations": ["Nairobi", "Remote"],
    "salaryMin": 200000,
    "autoApply": false
  },
  "shoppingPreferences": {
    "categories": ["electronics", "fashion"],
    "priceAlerts": true
  },
  "communicationStyle": {
    "tone": "casual",
    "language": "en",
    "briefUpdates": true
  },
  "notifications": {
    "channels": ["push", "sms"],
    "quietHours": { "start": "22:00", "end": "07:00" },
    "frequency": "important"
  },
  "proactiveActions": {
    "jobSearch": true,
    "priceMonitor": true,
    "invoiceReminders": true,
    "morningBrief": false
  }
}

Security

Authentication Security

• OTP expires in 5 minutes
• Max 3 OTP attempts
• Rate limiting per phone
• Session tokens rotate on sensitive actions
• Refresh tokens: 7 day expiry, single use

Data Protection

• Phone numbers hashed for lookups
• KYC documents stored encrypted (via YeboVerify)
• PII never logged
• GDPR/data deletion support

Open Questions

• [ ] Can users change their handle? (Premium feature?)
• [ ] What happens to handle if account deleted?
• [ ] Business accounts: separate handle namespace?
• [ ] Multi-device session handling?