Application Keys (API Tokens)

Table of Contents

1. Overview & M2M Authentication Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Layout
5. Field Reference & Token Parameters
6. Cryptographic Token Lifecycle & Generation
7. REST API Authorization & Rate Limiting Mechanics
8. Troubleshooting & Verification
9. Model Context Protocol (MCP) AI Integration
10. Glossary

---

1. Overview & M2M Authentication Architecture

In Ring2All SBC, the Application Keys module governs Machine-to-Machine (M2M) credentials, programmatic authentication tokens, and external automation access to the SBC REST API. Application keys allow monitoring daemons (e.g., Prometheus, Datadog), SIEM log forwarders, billing systems, and CI/CD pipelines to interact securely with the SBC without requiring interactive user logins or session cookies.

External System (Prometheus / CI/CD)                   Ring2All SBC REST API Gateway
                 │                                                   │
                 │─────── GET /api/v1/metrics/telemetry ────────────>│
                 │        Header: Authorization: Bearer sbc_live_... │
                 │                                                   │─── 1. Extract Key Prefix ─────┐
                 │                                                   │    Match "sbc_live_prom"      │
                 │                                                   │                               │
                 │                                                   │─── 2. Hash Token (SHA-256) ───┤
                 │                                                   │    Compare with key_hash      │
                 │                                                   │                               │
                 │                                                   │─── 3. Check Expiry & Rate ────┤
                 │                                                   │    Token Active & In-Quota?   │
                 │<────── HTTP 200 OK (JSON Telemetry Payload) ──────│<──────────────────────────────┘

Every token is cryptographically protected: the SBC only displays the raw plaintext token once during creation. The database stores strictly a one-way cryptographic SHA-256 hash (key_hash) along with a non-sensitive identification prefix (key_prefix).

---

2. Business & Operational Significance

• Headless Automation & Orchestration: Enables automated provisioning systems (Terraform, Ansible, custom customer portals) to dynamically create SIP accounts, add carrier gateways, or reload dispatchers.
• Perimeter SIEM & Metrics Harvesting: Empowers monitoring collectors to extract live Call Per Second (CPS), MOS scores, and registration counts at sub-minute intervals without exhausting web session pools.
• Granular Denial of Service Protection: Enforces dedicated per-token rate limits (Requests Per Minute - RPM), guaranteeing that a misconfigured external script cannot overwhelm the SBC API backend.
• Instant Blast-Radius Containment: If an external automation server is compromised, administrators can revoke its specific API key with a single click, neutralizing the threat without altering user passwords.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
DevOps Engineer	CI/CD & Pipeline Integration	Provision programmatic API tokens for infrastructure automation and automated dialplan deployments.
Infrastructure Architect	Telemetry & Observability Export	Authorize read-only tokens for Prometheus, Grafana, and ELK monitoring collectors.
Security Integrator	SIEM & Incident Event Ingestion	Configure scoped API keys for automated threat hunting and APIBAN integration daemons.
SBC Systems Administrator	Token Governance & Revocation	Audit active tokens, monitor usage counters, set expiration calendars, and revoke compromised keys.
AI Platform Copilot / Administration Agent	Automated Token Inventory & Security Auditing	Audit active REST API keys, monitor request consumption rates, detect expired tokens, and immediately revoke compromised keys via MCP.

---

4. Visual Interface & Layout

The Application Keys view consists of a token management DataGrid displaying active keys, rate limits, request counters, and expiration dates, along with a creation modal providing the one-time secret copy dialog.

4.1 Application Keys List View

Displays all generated API keys, their identification prefixes, assigned rate limits, total request counts, and operational statuses.

4.2 Application Key Configuration Form

Form modal used to define key name, description, expiration dates, and custom rate-limiting thresholds.

---

5. Field Reference & Token Parameters

Parameter Name	Data Type	Default	Description
Key Name	String	Prometheus Exporter	Descriptive administrative name identifying the service or daemon using the token.
Description	Text	Free text	Contextual notes detailing the external system, IP location, or operational scope.
Key Prefix	String	sbc_live_xxxx	Non-sensitive 12-character prefix used to identify the token in database indexes and audit logs.
Rate Limit (RPM)	Integer	1200	Maximum allowable HTTP requests per minute before the API returns 429 Too Many Requests.
Expires At	Date / Time	Optional	Expiration timestamp after which the token is automatically rejected by API middleware.
Status	Switch	Active	Enables or immediately revokes the token’s ability to authenticate requests.
Request Count	Counter	0	Cumulative total of successful API calls authenticated using this token.
Last Used At	Timestamp	Auto-updated	Most recent timestamp when a request was authenticated using this key.

---

6. Cryptographic Token Lifecycle & Generation

1. Entropy Generation: The platform generates a cryptographically secure 48-byte random token formatted as:

   sbc_live_9f8a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e

2. One-Way Storage: The token is immediately hashed via SHA-256 before insertion into the database table api_keys.
3. Prefix Indexing: The first 12 characters (sbc_live_9f8a) are stored in plaintext as key_prefix to allow sub-millisecond database lookups during request authentication.

---

7. REST API Authorization & Rate Limiting Mechanics

External clients authenticate by supplying the token in the standard HTTP Authorization header:

curl -X GET https://192.168.10.32/api/v1/routing/carriers \
     -H "Authorization: Bearer sbc_live_9f8a2b3c4d5e..." \
     -H "Accept: application/json"

Rate Limiting Headers

Every response includes standard RFC rate-limiting headers:

HTTP/2 200 OK
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1184
X-RateLimit-Reset: 1757268060

If the external application exceeds its assigned quota, the SBC terminates the request with HTTP/2 429 Too Many Requests.

---

8. Troubleshooting & Verification

Validating Token Authentication via CLI

Test an API key directly from a terminal:

curl -k -s -w "\nHTTP Status: %{http_code}\n" \
  -H "Authorization: Bearer YOUR_APPLICATION_KEY" \
  https://192.168.10.32/api/v1/health

Inspecting API Keys in Database

Review registered key prefixes and last usage timestamps:

sudo -u postgres psql -d sbc_admin -c "
SELECT id, name, key_prefix, rate_limit_rpm, is_active, last_used_at, request_count
FROM api_keys
ORDER BY id;
"

---

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 M2M API keys and programmatically revoke compromised tokens.

Available MCP Tools

Tool Name	Operation	Risk Level	Description
list_sbc_api_keys	Read	Low (read)	List REST API authentication application keys, key prefixes, scopes, rate limits, and expiration dates.
revoke_sbc_api_key	Mutate	High (operational)	Immediately revoke/deactivate a REST API key by UUID or name to prevent further programmatic access.

Tool Schemas & Parameter Definitions

list_sbc_api_keys

{
  "name": "list_sbc_api_keys",
  "description": "List REST API authentication application keys, key prefixes, scopes, rate limits, and expiration dates.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by key name or owner"
      }
    }
  }
}

revoke_sbc_api_key

{
  "name": "revoke_sbc_api_key",
  "description": "Immediately revoke/deactivate a REST API key by UUID or name to prevent further programmatic access.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "API key UUID or exact name to revoke"
      }
    },
    "required": ["identifier"]
  }
}

Realistic Payload Examples

Query Request (list_sbc_api_keys)

{
  "search": "Prometheus"
}

Successful Response (list_sbc_api_keys)

{
  "success": true,
  "data": {
    "apiKeys": [
      {
        "uuid": "2b9a7c41-61f2-4e9b-8321-7098c12a45fe",
        "name": "Prometheus Exporter",
        "description": "Telemetry and metrics collection daemon",
        "key_prefix": "sbc_live_9f8a",
        "scopes": ["metrics:read", "telemetry:read"],
        "rate_limit_rpm": 1200,
        "expires_at": "2027-01-01T00:00:00Z",
        "last_used_at": "2026-09-08T11:35:10Z",
        "request_count": 528940,
        "is_active": true,
        "owner_username": "admin",
        "created_at": "2026-01-15T08:00:00Z"
      }
    ],
    "total": 1
  }
}

Natural Language Prompt Scenarios

English (API Key Security Audit)

“List all active REST API keys on Ring2All SBC and verify if any key has exceeded 500,000 requests or is missing an expiration timestamp.”

Spanish (Revocación Inmediata de Token Comprometido)

“Revoca inmediatamente la API Key ‘Legacy Billing Sync’ debido a una fuga de credenciales detectada en el repositorio del cliente.”

Enterprise AI Safety Guardrails

• Zero Plaintext Secret Exposure: The platform strictly prevents retrieval of raw API key secrets after creation; MCP tools return only the non-sensitive 12-character key_prefix.
• Permanent Revocation State: Once an API key is revoked via revoke_sbc_api_key, its operational flag is set to is_active = false, immediately rejecting any further inbound HTTP requests.

---

10. Glossary

• M2M (Machine-to-Machine): Direct communication between devices or software agents using any communications channel without human intervention.
• Bearer Token: A security token where any party in possession of the token (the “bearer”) is granted access to the associated resources.
• SHA-256: A secure cryptographic hash algorithm producing a 256-bit fixed-size hash value, designed by the United States National Security Agency (NSA).
• RPM (Requests Per Minute): A rate-limiting metric that defines the maximum number of HTTP calls permitted in a sixty-second rolling window.