YeboID

One identity. All of Yebo.

---

What is YeboID?

YeboID is the identity layer for the entire Yebo ecosystem.

When you sign up for Yebo, you get:

• @handle — Your unique identity (e.g., @laslie)
• Phone + PIN — Simple authentication
• Profile — Follows you across all products
• Reputation — Trust built over time

---

Why Phone + PIN?

The Africa Reality

• Not everyone has email
• Passwords are forgotten
• Phone number is universal
• Mobile money uses PINs

The Solution

Sign Up:
Phone → OTP (once) → Create PIN → Choose @handle → Done

Sign In:
Phone + PIN → Done

Forgot PIN:
Phone → OTP → New PIN → Done

60 seconds to create. 5 seconds to sign in.

---

The @handle

What It Is

Your unique identifier across all Yebo products:

• @laslie
• @amara_trades
• @techshop

Where It's Used

• YeboShops: Your store URL
• YeboJobs: Your profile link
• Invoices: Your sender identity
• Reputation: Your public profile

Rules

• 3-30 characters
• Lowercase letters, numbers, underscores
• Unique (first come, first served)
• Can change (30-day cooldown)

---

Profile

What's Stored

Field	Public	Description
@handle	✅	Unique identifier
Name	✅	Display name
Avatar	✅	Profile picture
Bio	✅	Short description
KYC Status	✅	Verified badge
Phone	❌	Private
PIN	❌	Hashed, never exposed

Where It Appears

Your profile shows on:

• YeboShops listings
• YeboJobs applications
• Invoices you send
• Anywhere you interact

One profile. All products.

---

Authentication Flow

Sign Up

┌─────────────────────────────────────┐
│ Enter phone number                  │
│ [+268] [78 422 613]                │
│ [Continue]                          │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ Enter verification code             │
│ Sent to +26878422613                │
│ [1] [2] [3] [4] [5] [6]            │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ Create your PIN                     │
│ [•] [•] [•] [•] [•] [•]            │
│ Confirm PIN                         │
│ [•] [•] [•] [•] [•] [•]            │
└─────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────┐
│ Choose your @handle                 │
│ [@] [yourname]                      │
│ ✓ @yourname is available            │
│ [Create Account]                    │
└─────────────────────────────────────┘

Sign In

┌─────────────────────────────────────┐
│ Phone: [+268] [78 422 613]         │
│ PIN:   [•] [•] [•] [•]             │
│ [Sign In]                           │
└─────────────────────────────────────┘

---

Token System

Access Token

• JWT format
• 15 minutes expiry
• Contains: userId, handle, verified status
• Validated locally by all products (no API call)

Refresh Token

• Opaque string
• 30 days expiry
• Stored hashed in database
• Rotated on each use

Why This Works

All Yebo products share YEBOID_JWT_SECRET:

• Token issued by YeboID
• Validated locally by YeboShops, YeboJobs, etc.
• No API call needed
• Fast and scalable

---

Integration

For Yebo Products

// Install SDK
npm install @yeboid/node

// Protect routes
const { yeboidAuth } = require('@yeboid/node');

app.get('/api/orders', yeboidAuth.required, (req, res) => {
  const userId = req.yeboUserId;
  const handle = req.yeboHandle;
  // ... your logic
});

For Users

You: "Sign me into YeboShops"

Agent: "You're already signed in as @laslie.
What would you like to do?"

---

KYC Integration

Optional Verification

Users can verify identity via YeboVerify:

1. Upload ID document
2. Take selfie
3. AI verifies match

Benefits of Verification

• ✓ Badge on profile
• ✓ Higher transaction limits
• ✓ Trusted seller status
• ✓ Access to premium features

---

Security

PIN Security

• Hashed with bcrypt (cost 12)
• Never logged or exposed
• 5 failed attempts = 15 min lockout

Rate Limiting

• OTP send: 3/hour
• Sign in: 5/15 min
• Handle check: 30/min

Session Management

• View active sessions
• Revoke specific devices
• Logout all sessions

---

Database Schema

CREATE TABLE users (
  id UUID PRIMARY KEY,
  phone VARCHAR(20) UNIQUE NOT NULL,
  pin_hash VARCHAR(255) NOT NULL,
  handle VARCHAR(30) UNIQUE,
  name VARCHAR(100),
  avatar_url TEXT,
  kyc_status VARCHAR(20) DEFAULT 'none',
  created_at TIMESTAMP DEFAULT NOW()
);

---

Status

Component	Status
Specification	✅ Complete
Database Schema	✅ Complete
API Design	✅ Complete
Backend	🔄 Building
SDK	🔄 Building
Hub UI	🔄 Building

---

Related Docs

• Full YeboID Documentation — Detailed technical docs
• Architecture: Identity — How it integrates