Building Apps on Signal Telecom Suite

How consumer apps, enterprise portals, and vertical-specific platforms (agri, healthcare, finance) integrate with the Signal Telecom Suite API. White-label ready, multi-tenant, schema-isolated.

1. Architecture Overview

Signal Telecom Suite is a platform, not an app. It exposes REST APIs that any frontend can consume.

2. Authentication

2.1 Tenant Login (operator/sandbox)

For admin portals and operator dashboards. Returns tenant config and sets the tenant context.

POST /api/v1/tenant/login
Content-Type: application/json

{
  "email": "ops@prairieconnect.us",
  "password": "demo2024"
}

Response:
{
  "tenant": {
    "id": 2,
    "name": "Prairie Connect Broadband",
    "slug": "prairie",
    "schema": "tenant_prairie",
    "countries": ["US"],
    "modules_enabled": ["SIG-ID", "SIG-PROV", ...]
  }
}

After login, include X-Tenant-ID: 2 header on all subsequent API calls.

2.2 Consumer Login (subscriber-facing apps)

For consumer apps and self-serve portals. Authenticates by phone number + password.

POST /api/v1/auth/consumer-login
Content-Type: application/json

{
  "phone": "+13125550101",
  "password": "Signal2024!"
}

Response:
{
  "customer_id": "069b5d5b-27b6-...",
  "external_id": "CCA-US-d8d5f8e2",
  "name": "Midwest Grain Co-op",
  "tenant_id": 2,
  ...
}

Use the returned tenant_id as X-Tenant-ID header for subsequent calls. Use customer_id for customer-specific API calls.

3. Common API Patterns

3.1 Headers

X-Tenant-ID: 2              # Required on every request
Content-Type: application/json

3.2 Paginated Responses

List endpoints return paginated results:

GET /api/v1/customers/?limit=20&offset=0

{
  "items": [...],
  "total": 142,
  "limit": 20,
  "offset": 0
}

3.3 Tenant Isolation

Every request is scoped to the tenant's PostgreSQL schema. Tenant 1 cannot see tenant 2's data. This is enforced at the database level (schema-per-tenant) and application level (tenant_id filtering).

4. Building a Consumer App

A consumer app (like T-Mobile T-Life) needs these APIs:

Example: Fetch usage data

// React / JavaScript
const API = 'https://api.telecom.signalailabs.com/api/v1';
const headers = {
  'X-Tenant-ID': session.tenant_id,
  'Content-Type': 'application/json',
};

// Get usage summary
const usage = await fetch(
  `${API}/rating/usage-summary/${session.customer_id}`,
  { headers }
).then(r => r.json());

console.log(usage.total_mb);        // 2750.0
console.log(usage.total_voice_min); // 100
console.log(usage.total_sms);       // 20

5. Building a Vertical Platform (e.g., Signal Agri)

A vertical platform imports common modules from sigcore as a Python package and adds its own domain-specific modules.

5.1 Package Structure

signal-agri/
  src/sigagri/
    marketplace/    # Agri-specific: listings, orders
    inventory/      # Agri-specific: warehouses, stock
    certifications/ # Agri-specific: organic, fair-trade
    traceability/   # Agri-specific: batch tracking, QR
    main.py         # FastAPI app
  portal/           # Farmer portal (React)

# sigagri/main.py imports common modules:
from sigcore.bss.identity.router import router as identity_router
from sigcore.bss.billing.router import router as billing_router
from sigcore.bss.payments.router import router as payments_router
from sigcore.bss.tickets.router import router as tickets_router
# ... plus agri-specific routers
from sigagri.marketplace.router import router as marketplace_router

5.2 What you get for free from sigcore

5.3 What you build yourself

6. Building an Enterprise Self-Serve Portal

An enterprise self-serve portal lets business customers manage their own account without calling support.

7. API URL Configuration

Never hardcode API URLs. Use environment variables:

# .env.production
VITE_API_URL=https://api.telecom.signalailabs.com/api/v1

# In code
const API = import.meta.env.VITE_API_URL;

8. CORS

The platform API allows requests from configured origins. For a new consumer app, add its domain to the CORS allow list in sigtel/main.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://app.tracconnect.rw",      # TrAC consumer app
        "https://my.prairieconnect.us",     # Prairie self-serve
        "https://sandbox.signalailabs.com", # Sandbox portal
        ...
    ],
)

9. Enterprise MVNO Integration

For MVNOs selling to corporate/enterprise customers with bulk SIM needs:

9.1 Create Enterprise Account

POST /api/v1/mvno/enterprise
{
  "customer_id": "069b...",        // Enterprise customer from SIG-ID
  "account_name": "Infosys - Corporate Mobile",
  "max_sims": 500,
  "billing_mode": "cost_center",   // consolidated, per_sim, cost_center
  "volume_discount_pct": 15.0
}

9.2 Bulk SIM Assignment

POST /api/v1/mvno/enterprise/bulk-assign
{
  "enterprise_account_id": 1,
  "iccids": ["8991000000001", "8991000000002", ...],  // up to 500 per call
  "cost_center": "BLR-ENG",
  "department": "Engineering"
}

Response: { "assigned": 10, "failed": 0, "errors": [] }

9.3 Bulk Operations

9.4 Billing Modes

10. OpenAPI Specs

Download the OpenAPI spec to generate client SDKs in any language:

Generate a TypeScript client:

npx openapi-typescript-codegen \
  --input https://api.telecom.signalailabs.com/docs/bss/openapi.json \
  --output src/api \
  --client fetch