SaaS & Billing Documentation

Overview

Architecture Components

Pricing Plans

Feature Comparison

Gatekeeper System

The Gatekeeper is the authentication and licensing layer that ensures only authorized users can access the system.

How It Works

1. User attempts login with credentials
   ↓
2. Gatekeeper checks local database
   - Is user registered?
   - Is subscription active?
   - Are quotas exceeded?
   ↓
3. If authorized, authenticate with CommuniGate Pro
   ↓
4. Generate JWT token with both contexts
   ↓
5. Return token for API access

Database Schema

-- Gatekeeper Users
CREATE TABLE gatekeeper_users (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(50),  -- super_admin, admin, user
    cgpro_domain VARCHAR(255),
    cgpro_admin_user VARCHAR(255),
    status VARCHAR(50) DEFAULT 'active',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- Master Permissions
CREATE TABLE master_permissions (
    id UUID PRIMARY KEY,
    user_email VARCHAR(255) REFERENCES gatekeeper_users(email),
    permission VARCHAR(255) NOT NULL,
    granted_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Authentication Flow

// POST /api/v2/auth/gatekeeper-login
{
  "email": "user@domain.com",
  "password": "gatekeeper_password",
  "cgpro_password": "communigate_password"  // Optional if different
}

// Response
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "email": "user@domain.com",
    "role": "admin",
    "permissions": ["manage_users", "manage_resources"]
  },
  "subscription": {
    "plan": "premium",
    "valid_until": "2025-12-31T23:59:59Z"
  }
}

Subscription Management

Customer Portal

Customers can manage their subscriptions at http://gatekeeper.core.at

Subscription API

// Get current subscription
GET /api/v2/saas/subscription
Authorization: Bearer {token}

// Response
{
  "subscription": {
    "id": "sub_123456",
    "plan_type": "premium",
    "status": "active",
    "valid_until": "2025-12-31T23:59:59Z",
    "next_billing": "2025-09-01T00:00:00Z",
    "usage": {
      "users": { "current": 45, "limit": 200 },
      "resources": { "current": 78, "limit": 500 },
      "api_calls": { "current": 12543, "limit": 50000 },
      "storage_gb": { "current": 8.5, "limit": 50 }
    }
  }
}

// Upgrade subscription
POST /api/v2/saas/subscription/upgrade
{
  "plan_type": "enterprise",
  "billing_period": "yearly"
}

Access Tokens

Access tokens provide secure API access without exposing passwords.

Token Types

Token Management

// Generate new access token
POST /api/v2/saas/access-token/regenerate
Authorization: Bearer {jwt_token}

// Response
{
  "success": true,
  "token": "tok_abc123xyz789",
  "expires_at": "2025-09-21T00:00:00Z"
}

// Validate token
POST /api/v2/saas/validate-token
{
  "token": "tok_abc123xyz789"
}

// Revoke token
DELETE /api/v2/saas/access-token/{token_id}
Authorization: Bearer {jwt_token}

Using Tokens

# Using JWT token
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
     https://[your-server]/api/v2/resources

# Using API key
curl -H "X-API-Key: tok_abc123xyz789" \
     https://[your-server]/api/v2/resources

# Using access token in URL (not recommended)
curl https://[your-server]/api/v2/resources?access_token=tok_abc123xyz789

Usage Tracking

Metrics Collected

• API Calls: Every API request with endpoint, method, response time
• Active Users: Unique users per billing period
• Resource Count: Number of resources created
• Storage: Files, attachments, and database usage
• Bandwidth: Data transfer in/out

Usage API

// Get usage statistics
GET /api/v2/saas/usage?period=current_month
Authorization: Bearer {token}

// Response
{
  "usage": {
    "period": {
      "start": "2025-08-01T00:00:00Z",
      "end": "2025-08-31T23:59:59Z"
    },
    "api_calls": {
      "total": 12543,
      "by_endpoint": {
        "/resources": 3421,
        "/bookings": 2156,
        "/calendars": 1987
      },
      "by_day": [
        { "date": "2025-08-01", "count": 423 },
        { "date": "2025-08-02", "count": 512 }
      ]
    },
    "users": {
      "active": 45,
      "new": 3,
      "by_role": {
        "admin": 5,
        "manager": 12,
        "user": 28
      }
    },
    "storage_bytes": 9126805504,
    "bandwidth_bytes": {
      "in": 1234567890,
      "out": 9876543210
    }
  }
}

Quota Enforcement

// Check remaining quota
GET /api/v2/saas/quota
Authorization: Bearer {token}

// Response when quota exceeded
{
  "error": "Quota exceeded",
  "details": {
    "type": "api_calls",
    "limit": 10000,
    "used": 10001,
    "reset_at": "2025-09-01T00:00:00Z"
  },
  "upgrade_url": "https://gatekeeper.core.at/upgrade"
}

Billing & Invoicing

Billing Cycle

1. Usage Collection: Daily aggregation of metrics
2. Invoice Generation: Monthly on subscription anniversary
3. Payment Processing: Automatic charge to payment method
4. Receipt Delivery: Email with PDF invoice

Invoice API

// List invoices
GET /api/v2/saas/invoices
Authorization: Bearer {token}

// Get specific invoice
GET /api/v2/saas/invoices/{invoice_id}

// Download PDF
GET /api/v2/saas/invoices/{invoice_id}/pdf

// Invoice structure
{
  "invoice": {
    "id": "inv_20250801_001",
    "number": "INV-2025-0801",
    "customer": {
      "email": "customer@company.com",
      "company": "ACME Corp"
    },
    "period": {
      "start": "2025-08-01",
      "end": "2025-08-31"
    },
    "line_items": [
      {
        "description": "Premium Plan - Monthly",
        "quantity": 1,
        "unit_price": 149.99,
        "total": 149.99
      },
      {
        "description": "Additional API calls (5,000)",
        "quantity": 5000,
        "unit_price": 0.001,
        "total": 5.00
      }
    ],
    "subtotal": 154.99,
    "tax": 29.45,
    "total": 184.44,
    "status": "paid",
    "paid_at": "2025-09-01T08:30:00Z"
  }
}

Payment Methods

// Add payment method
POST /api/v2/saas/payment-methods
{
  "type": "credit_card",
  "card_number": "4111111111111111",
  "exp_month": 12,
  "exp_year": 2027,
  "cvc": "123",
  "is_default": true
}

// List payment methods
GET /api/v2/saas/payment-methods

// Set default
PUT /api/v2/saas/payment-methods/{method_id}/default

API Integration for SaaS

Webhook Events

Configure webhooks to receive real-time notifications about subscription events.

// Configure webhook
POST /api/v2/saas/webhooks
{
  "url": "https://your-app.com/webhooks/rmp",
  "events": [
    "subscription.created",
    "subscription.updated",
    "subscription.cancelled",
    "invoice.created",
    "invoice.paid",
    "quota.exceeded"
  ],
  "secret": "webhook_secret_key"
}

// Webhook payload example
{
  "event": "subscription.updated",
  "timestamp": "2025-08-21T12:00:00Z",
  "data": {
    "subscription_id": "sub_123",
    "customer_email": "customer@company.com",
    "old_plan": "standard",
    "new_plan": "premium",
    "effective_date": "2025-08-21T12:00:00Z"
  },
  "signature": "sha256=abc123..."  // HMAC-SHA256 of payload
}

Rate Limiting

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1630454400
Retry-After: 3600

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 100 requests per hour",
  "retry_after": 3600
}

Migration Guide

Migrating from v1.0 to v2.0 SaaS

Data Export from v1.0

# Export resources
pg_dump -h localhost -U rmp_user -d rmp_v1 \
  -t resources -t resource_types -t bookings \
  > rmp_v1_export.sql

# Export user data
pg_dump -h localhost -U rmp_user -d rmp_v1 \
  -t users -t permissions \
  > rmp_v1_users.sql

Import to v2.0

// Import script
POST /api/v2/admin/import
{
  "source": "rmp_v1",
  "customer_email": "customer@company.com",
  "data": {
    "resources": [...],
    "bookings": [...],
    "users": [...]
  },
  "options": {
    "preserve_ids": true,
    "skip_duplicates": true,
    "send_notifications": false
  }
}

API Compatibility