---
title: "Carrier API Keys (Wholesale Partner Credentials)"
description: "Documentation for Carrier API Keys"
---

## Table of Contents
1. [Overview & Carrier Integration Architecture](#1-overview--carrier-integration-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & Provider Parameters](#5-field-reference--provider-parameters)
6. [Automated Telephony Integration Workflows](#6-automated-telephony-integration-workflows)
7. [Credential Vaulting & Storage Security](#7-credential-vaulting--storage-security)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#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.

![Carrier API Keys List View](/screenshots/sbc/admin/carrier-api-keys/carrier-api-keys-list.png)

### 4.2 Carrier API Key Configuration Form
Form modal used to configure carrier provider types, API keys, secret credentials, base endpoints, and administrative notes.

![Carrier API Key Configuration Form](/screenshots/sbc/admin/carrier-api-keys/carrier-api-key-form.png)

---

## 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:

```sql
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:
```bash
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:
```bash
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`
```json
{
  "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`
```json
{
  "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`)
```json
{
  "identifier": "Telnyx Wholesale Voice"
}
```

#### Successful Response (`get_sbc_carrier_api_key_status`)
```json
{
  "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.