--- title: "Application Keys (API Tokens)" description: "Documentation for Application Keys" --- ## Table of Contents 1. [Overview & M2M Authentication Architecture](#1-overview--m2m-authentication-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 & Token Parameters](#5-field-reference--token-parameters) 6. [Cryptographic Token Lifecycle & Generation](#6-cryptographic-token-lifecycle--generation) 7. [REST API Authorization & Rate Limiting Mechanics](#7-rest-api-authorization--rate-limiting-mechanics) 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 & 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. ![Application Keys List View](/screenshots/sbc/admin/api-keys/api-keys-list.png) ### 4.2 Application Key Configuration Form Form modal used to define key name, description, expiration dates, and custom rate-limiting thresholds. ![Application Key Configuration Form](/screenshots/sbc/admin/api-keys/api-key-form.png) --- ## 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: ```text 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: ```bash 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 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: ```bash 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: ```bash 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` ```json { "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` ```json { "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`) ```json { "search": "Prometheus" } ``` #### Successful Response (`list_sbc_api_keys`) ```json { "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.