Carrier API Keys (Wholesale Partner Credentials)

Table of Contents

1. Overview & Carrier Integration Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Layout
5. Field Reference & Provider Parameters
6. Automated Telephony Integration Workflows
7. Credential Vaulting & Storage Security
8. Troubleshooting & Verification
9. Model Context Protocol (MCP) AI Integration
10. Glossary

---

1. Overview & Carrier Integration Architecture

In Ring2All SBC, the Carrier API Keys module manages outbound REST API credentials, authentication tokens, and API endpoints for upstream telecommunications providers (e.g., Telnyx, Twilio, Bandwidth, Inteliquent, and custom wholesale carriers). Unlike standard SIP trunking (which operates over UDP/TCP/TLS for session signaling), Carrier API keys allow the SBC backend to interact with the carrier’s administrative control plane.

┌─────────────────────────────────────────────────────────────┐
│                  Ring2All SBC Core Backend                  │
└──────────────┬──────────────────────────────┬───────────────┘
               │                              │
     SIP Signaling (Port 5060/5061)     REST API (HTTPS 443)
     • Voice Media (RTP)                • Automated DID Ordering
     • Session Establishment            • LCR Rate Sheet Sync
               │                        • Carrier Gateway Health
               ▼                              ▼
┌──────────────────────────────┐┌──────────────────────────────┐
│  Carrier SIP Interconnect    ││   Carrier Cloud REST API     │
│    (Sipwise / Kamailio)      ││   (api.telnyx.com / twilio)  │
└──────────────────────────────┘└──────────────────────────────┘

Through these authenticated API channels, the SBC automates Direct Inward Dialing (DID) number ordering, synchronizes real-time termination rate sheets, and queries remote carrier network operational status.

---

2. Business & Operational Significance

• Zero-Touch DID Provisioning: Automatically reserves, orders, and binds geographic telephone numbers from carrier inventories directly into the SBC routing tables without manual carrier portal logins.
• Automated Least Cost Routing (LCR) Updates: Periodically ingests updated tariff sheets and prefix price adjustments directly from carrier REST endpoints, keeping MTrees prefix tables accurate.
• Out-of-Band Carrier Health Monitoring: Queries remote carrier status endpoints to detect regional outages or planned maintenance before SIP options keepalive timeouts fail.
• Consolidated Multi-Carrier Vault: Centralizes diverse provider authentication schemes (Basic Auth, Bearer Tokens, Account SID/Secret pairs) in a single secure administrative interface.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
Carrier Relations Manager	Upstream Interconnect Provisioning	Register wholesale carrier accounts, store administrative API secrets, and configure API endpoints.
Interconnect Provisioning Specialist	Automated Inventory Management	Execute automated DID procurement and manage number porting workflows across carrier APIs.
Telecom Billing Analyst	Dynamic Rate Card Synchronization	Configure automated tariff imports to ensure real-time routing aligns with agreed per-minute wholesale pricing.
SBC Systems Administrator	Credential Security Governance	Maintain secure API token storage, review carrier endpoint reachability, and rotate carrier secrets.
AI Platform Copilot / Administration Agent	Automated Interconnect Auditing & Provider Status Verification	Audit wholesale carrier API integrations, verify connectivity statuses, check provider configurations, and assist in trunk troubleshooting via MCP.

---

4. Visual Interface & Layout

The Carrier API Keys interface consists of an upstream provider catalog displaying all configured carrier APIs, supported features, and gateway linkages, along with a dedicated modal editor for key registration.

4.1 Carrier API Keys List View

Displays registered carrier API integrations, underlying carrier names, API provider types, base URLs, and active statuses.

4.2 Carrier API Key Configuration Form

Form modal used to configure carrier provider types, API keys, secret credentials, base endpoints, and administrative notes.

---

5. Field Reference & Provider Parameters

Field Name	Data Type	Options / Examples	Description
Carrier Name	String	Text (e.g., Telnyx Wholesale Voice)	Descriptive label identifying the telecommunications carrier.
Carrier ID	Integer	Foreign Key (dr_gateways.gwid)	Links these API credentials to the corresponding SIP carrier gateway in the Dispatcher.
Provider Type	Select	telnyx, twilio, bandwidth, custom	Selects the API driver and JSON payload formatting used for carrier communications.
API Key / Account SID	String	Text / Alphanumeric	The public identifier or username required by the carrier’s REST API (e.g., Twilio Account SID).
API Secret / Token	Password	Text / Alphanumeric	The secret authentication token or Bearer key passed in HTTP authorization headers.
Base API URL	URL	https://api.telnyx.com/v2	The primary root URL of the carrier’s REST API interface.
Operational Status	Select	Active, Testing, Suspended	Status controlling whether background jobs can dispatch automated API calls to this provider.
Notes	Text	Free text	Administrative documentation, contract account numbers, or support ticket references.

---

6. Automated Telephony Integration Workflows

6.1 Automated DID Procurement

When a customer PBX orders a new phone number through the portal:

1. The SBC backend queries the carrier API endpoint using stored credentials to search available inventory.
2. An order is submitted via POST /v2/number_orders.
3. Upon order confirmation, the SBC automatically provisions the number in the local DID routing table and creates the inbound dialplan entry.

6.2 LCR Tariff Synchronization

Periodic background workers query carrier rate sheet endpoints to fetch per-prefix costs, updating database tariffs and alerting NOC engineers if wholesale termination rates increase.

---

7. Credential Vaulting & Storage Security

All carrier credentials are stored securely in PostgreSQL with column-level encryption:

CREATE TABLE carrier_api_keys (
    id SERIAL PRIMARY KEY,
    uuid UUID NOT NULL DEFAULT gen_random_uuid(),
    carrier_id INT NOT NULL,
    carrier_name VARCHAR(100) NOT NULL,
    provider VARCHAR(32) NOT NULL,
    api_key VARCHAR(128) NOT NULL,
    api_secret TEXT NOT NULL, -- AES-256-GCM Encrypted
    base_url VARCHAR(255),
    status VARCHAR(16) NOT NULL DEFAULT 'active',
    notes TEXT,
    created_at TIMESTAMPTZ NOT NULL,
    updated_at TIMESTAMPTZ NOT NULL
);

• AES-256-GCM Encryption: Carrier secrets and private tokens are encrypted using an encryption key managed by the host environment before being written to disk.
• Masked Display: In the web UI, existing secrets are masked by default (••••••••••••••••), preventing shoulder surfing and unauthorized credential copying.

---

8. Troubleshooting & Verification

Inspecting Carrier API Keys in Database

To review registered carrier integrations directly on the SBC:

sudo -u postgres psql -d sbc_admin -c "
SELECT id, carrier_name, provider, base_url, status, created_at
FROM carrier_api_keys
ORDER BY id;
"

Probing Carrier API Reachability

Validate that the carrier’s REST endpoint is reachable from the SBC host:

curl -sI https://api.telnyx.com/v2/

Ensure that DNS resolution succeeds and the carrier gateway returns a valid HTTP response (e.g., HTTP/2 200 or HTTP/2 401 Unauthorized indicating correct path routing).

---

9. Model Context Protocol (MCP) AI Integration

Ring2All SBC exposes dedicated Model Context Protocol (MCP) tools enabling AI agents, autonomous NOC bots, and administrative copilot assistants to audit wholesale carrier API credentials and inspect upstream interconnect configurations safely.

Available MCP Tools

Tool Name	Operation	Risk Level	Description
list_sbc_carrier_api_keys	Read	Low (read)	List carrier provisioning API credentials (Twilio, Telnyx, Bandwidth, etc.) with provider type and connection status (secrets masked).
get_sbc_carrier_api_key_status	Read	Low (read)	Audit status, configuration details, and provider metadata for a carrier API key by carrier ID, carrier name, or numeric ID.

Tool Schemas & Parameter Definitions

list_sbc_carrier_api_keys

{
  "name": "list_sbc_carrier_api_keys",
  "description": "List carrier provisioning API credentials (Twilio, Telnyx, Bandwidth, etc.) with provider type and connection status (secrets masked).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by carrier name or provider"
      }
    }
  }
}

get_sbc_carrier_api_key_status

{
  "name": "get_sbc_carrier_api_key_status",
  "description": "Audit status, configuration details, and provider metadata for a carrier API key by carrier ID, carrier name, or numeric ID.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "Carrier ID (numeric), carrier name, or record ID"
      }
    },
    "required": ["identifier"]
  }
}

Realistic Payload Examples

Query Request (get_sbc_carrier_api_key_status)

{
  "identifier": "Telnyx Wholesale Voice"
}

Successful Response (get_sbc_carrier_api_key_status)

{
  "success": true,
  "data": {
    "carrierApiKey": {
      "id": 1,
      "carrier_id": 101,
      "carrier_name": "Telnyx Wholesale Voice",
      "provider": "telnyx",
      "api_key": "KEY018293A7F_TLNX",
      "api_secret": "********",
      "base_url": "https://api.telnyx.com/v2",
      "status": "active",
      "notes": "Primary wholesale termination & DID ordering partner",
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-08-15T10:30:00Z"
    }
  }
}

Natural Language Prompt Scenarios

English (Carrier Interconnect API Audit)

“List all configured carrier API integrations on Ring2All SBC and verify if the Telnyx provisioning endpoint is set to active.”

Spanish (Inspección de Credenciales de Carrier)

“Verifica el estado de la integración de API del carrier ‘Telnyx Wholesale Voice’ y comprueba la URL base configurada para aprovisionamiento.”

Enterprise AI Safety Guardrails

• Strict Secret Redaction: Private carrier secrets (api_secret, bearer tokens) are permanently replaced with '********' in all MCP JSON responses, guaranteeing zero credential leakage to LLM memory.
• Read-Only Scope: The MCP tools provide analytical status verification, preventing autonomous modification of billing and tariff endpoints.

---

10. Glossary

• DID (Direct Inward Dialing): A telecommunications service that connects a block of telephone numbers directly to an organization’s PBX or SBC.
• LNP (Local Number Portability): The legal process allowing telephone customers to retain their existing numbers when switching service providers.
• Account SID: A unique identifier used by certain telecom API providers (such as Twilio) to identify an administrative account.
• Rate Sheet: A structured table listing per-minute costs for voice termination broken down by country codes and regional prefixes.