hub/docs/architecture/API.md

🔌 Cannabrands API Reference

🎯 Overview

The Cannabrands API provides endpoints for business management, user authentication, notifications, and setup workflows. All business routes are prefixed with /b/ following the Marketplace Platform-style URL structure.

🔐 Authentication

Session-Based Authentication

All API endpoints require Laravel session authentication. Users must be logged in through the web interface.

CSRF Protection

All POST/PUT/DELETE requests require CSRF token in headers:

'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').getAttribute('content')

🏢 Business Authentication Routes

Registration

Method	Endpoint	Purpose	Middleware
GET	/b/register	Show registration form	guest
POST	/b/register	Process registration	guest
GET	/b/registration/success	Registration success page	guest

Login/Logout

Method	Endpoint	Purpose	Middleware
GET	/b/login	Show login form	guest
POST	/b/login	Process login	guest
POST	/b/logout	Logout user	auth

Profile Management

Method	Endpoint	Purpose	Middleware
GET	/b/profile	User profile (no business)	auth, verified

🎛 Dashboard Routes

Main Dashboard

Method	Endpoint	Purpose	Middleware
GET	/b/dashboard	Business dashboard	auth, verified, approved
GET	/dashboard	Legacy redirect to /b/dashboard	auth, verified, approved

🛠 Business Setup Routes

Multi-Step Setup Wizard

Method	Endpoint	Purpose	Middleware
GET	/b/setup	Setup wizard (step 1)	auth, verified, approved
GET	/b/setup/{step}	Specific setup step (1-5)	auth, verified, approved
POST	/b/setup/{step}	Submit setup step	auth, verified, approved

Setup Step Breakdown

1. Step 1: Business Information (name, type, address)
2. Step 2: Contact & Billing Information
3. Step 3: License Information
4. Step 4: Banking & Tax Information
5. Step 5: Review & Submit

🔔 Notification API

Notification Endpoints

Method	Endpoint	Purpose	Response
GET	/b/notifications	Notifications center page	HTML
GET	/b/notifications/dropdown	Dropdown data	JSON
GET	/b/notifications/count	Unread count	JSON
POST	/b/notifications/{id}/read	Mark as read	JSON
POST	/b/notifications/{id}/unread	Mark as unread	JSON
POST	/b/notifications/read-all	Mark all as read	JSON

Notification API Responses

Dropdown Data (/b/notifications/dropdown)

{
  "notifications": [
    {
      "id": "uuid",
      "type": "business_setup",
      "title": "Complete Your Business Profile",
      "message": "Welcome to Cannabrands! Complete your...",
      "icon": "building",
      "color": "primary",
      "action_url": "/b/setup",
      "action_text": "Complete Profile",
      "priority": "normal",
      "created_at": "2 hours ago",
      "read_at": null,
      "is_unread": true
    }
  ],
  "unread_count": 3,
  "has_more": true
}

Unread Count (/b/notifications/count)

{
  "unread_count": 5
}

Mark as Read (/b/notifications/{id}/read)

{
  "success": true
}

👥 User Management (Filament Admin)

Admin Panel Routes

Endpoint	Purpose	Access
/admin	Filament admin dashboard	Admin only
/admin/users	User management	Admin only
/admin/businesses	Business management	Admin only

User Approval Actions

• View/Modify: Edit user details
• Approve: Grant business access
• Deny: Reject business access

🔄 Special Routes

Approval System

Method	Endpoint	Purpose	Middleware
GET	/approval/login/{user}	Signed URL login	signed
GET	/pending-approval	Pending approval page	auth

System Routes

Method	Endpoint	Purpose
GET	/version	Application version
GET	/status	System status check

📊 Data Formats

User Registration Data

{
  "first_name": "John",
  "last_name": "Doe", 
  "phone": "555-123-4567",
  "position": "owner",
  "email": "john@business.com",
  "password": "password",
  "password_confirmation": "password",
  "business_name": "Green Valley Dispensary",
  "market": "California",
  "terms": true
}

Business Setup Data

{
  "name": "Green Valley Dispensary",
  "business_type": "dispensary",
  "entity_type": "LLC",
  "ein_tax_id": "12-3456789",
  "address": "123 Main St",
  "city": "Los Angeles",
  "state": "CA",
  "zip": "90210",
  "phone": "555-123-4567",
  "email": "contact@greenvalley.com"
}

🚨 Error Handling

Common HTTP Status Codes

• 200: Success
• 302: Redirect (often to login or dashboard)
• 401: Unauthenticated
• 403: Forbidden (not approved or wrong user type)
• 404: Not found
• 422: Validation error
• 500: Server error

Error Response Format

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password field is required."]
  }
}

📈 Rate Limiting

Default Limits

• Web routes: 60 requests per minute per IP
• API routes: 60 requests per minute per user
• Login attempts: 5 attempts per minute per email

🔒 Security

CSRF Protection

All state-changing requests require CSRF token.

Route Model Binding

User notifications automatically scope to authenticated user.

Middleware Stack

• web: Session, CSRF, cookie encryption
• auth: Requires authentication
• verified: Requires email verification
• approved: Requires admin approval
• guest: Unauthenticated users only

🧪 Testing Endpoints

Development Only

# Send test notifications
POST /dev/notifications/test/{user_id}

# Reset user setup progress  
POST /dev/users/{id}/reset-setup

---

Last Updated: August 2025
Base URL: http://localhost:8000 (development)
Authentication: Laravel session-based