Vela Mobile API Documentation

MW API DOC

System Settings

Previous Next

Admin endpoints for managing carrier configuration at runtime. All settings endpoints require superuser authentication.

Carrier credentials (API keys) are managed via environment variables and are never exposed through the API.

List All Settings

Endpoint: GET /settings/

Auth: Superuser only

Response Example

[
  {
    "key": "default_carrier",
    "value": "\"321\"",
    "description": "Default carrier for new users and plans",
    "updated_at": "2026-08-06T12:00:00Z"
  },
  {
    "key": "carriers_enabled",
    "value": "{\"321\": true, \"pwgns\": true}",
    "description": "Enable/disable carriers globally",
    "updated_at": "2026-08-06T12:00:00Z"
  },
  {
    "key": "maintenance_mode",
    "value": "false",
    "description": "Disable all carrier operations when true",
    "updated_at": "2026-08-06T12:00:00Z"
  }
]

Get Setting

Endpoint: GET /settings/{key}

Auth: Superuser only

Parameter Location Type Required Description
key Path string Yes Setting key name

Update Setting

Endpoint: PUT /settings/{key}

Auth: Superuser only

Request Body

Field Type Required Description
value string Yes New value (must be valid JSON)

Validation Rules

  • default_carrier: Must be "321" or "pwgns". Cannot set to a disabled carrier.
  • carriers_enabled: Must be a JSON object. At least one carrier must remain enabled. Cannot disable the current default carrier.
  • maintenance_mode: Must be true or false.

Request Example

{
  "value": "\"pwgns\""
}

Warning

Setting values are JSON-encoded. Strings must be wrapped in quotes: "\"321\"" not "321".

Carrier Status

Endpoint: GET /settings/carriers/status

Auth: Superuser only

Returns the health status of all carriers without exposing credentials.

Response Example

[
  {
    "carrier": "321",
    "enabled": true,
    "credentials_configured": true,
    "display_name": "321 Communications"
  },
  {
    "carrier": "pwgns",
    "enabled": true,
    "credentials_configured": false,
    "display_name": "PWGNS"
  }
]

Fields

Field Description
carrier Carrier identifier
enabled Whether admin has enabled this carrier
credentials_configured Whether API credentials exist in environment (true/false only — values never exposed)
display_name Human-readable carrier name

Available Settings Keys

Key Type Default Description
default_carrier string "321" Default carrier for new users/plans
carriers_enabled object {"321": true, "pwgns": true} Enable/disable carriers globally
carrier_321_display_name string "321 Communications" Display name in UI
carrier_pwgns_display_name string "PWGNS" Display name in UI
maintenance_mode boolean false Disable all carrier operations (503)

Per-Plan Carrier Resolution

Plans can be assigned to a specific carrier. When a request includes a plan_id (activation, port-in, plan change, purchase, reconnect), the system resolves the carrier in this order:

  1. Plan's carrier — if the plan has a carrier field set ("321" or "pwgns"), that carrier is used
  2. User's preference — if the user has a carrier_preference set, that is used
  3. System default — the default_carrier setting from admin settings

This allows different plans to route to different carriers automatically.

Plan Carrier Field

When creating or updating a plan via the Plan Management API, you can set the carrier field:

{
  "name": "Premium 5G Plan",
  "carrier_plan_id": "2059",
  "carrier": "321",
  "description": "Unlimited 5G plan on 321 Communications",
  "price": 55.00
}
Value Meaning
"321" Route to 321 Communications
"pwgns" Route to PWGNS
null Use system default carrier

User Carrier Preference

Users can have a carrier_preference field set by an admin. This acts as a fallback when a plan doesn't specify a carrier.

Resolution Flow Diagram

Request with plan_id
        │
        ▼
┌─ Plan has carrier? ──── YES → Use plan.carrier
│       │
│       NO
│       │
│       ▼
├─ User has preference? ─ YES → Use user.carrier_preference
│       │
│       NO
│       │
│       ▼
└─ Use system default_carrier setting
Callbacks Best Practices