---
title: "API Keys Module Documentation"
description: "Documentation for Application Keys"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Common Scenarios & Examples](#6-common-scenarios--examples)
10. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Application Keys (API Keys) module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Admin**.
3. Under **Administration**, click **Application Keys** (`/admin/admin/app-keys`).
4. To generate a new application key, click the **+ Add Application Key** button.
5. To view, edit, regenerate, or revoke an existing key, click on the row or the action controls (`/admin/admin/app-keys/:id`).

---

## Screenshots & Visual Interface

### Application Keys List View
The Application Keys overview lists all active and revoked service credentials with their key names, key prefixes, tenant assignments, domain scoping, creation dates, expiration timestamps, and status indicators.
![Application Keys List](/screenshots/admin/admin/application-keys-list.png)

### Application Key Generation & Scoping Form
The application key configuration form manages key name metadata, secret token generation, IP address whitelisting, tenant/domain boundaries, and granular API module permissions.
![Application Key Configuration Form](/screenshots/admin/admin/application-keys-form.png)

---

## 🎯 User Roles & Key Capabilities

The Application Keys module provisions and secures machine-to-machine integrations across enterprise systems:

| Role | Key Capabilities & Operational Scope |
|------|--------------------------------------|
| **Super Administrator** | Generates system-wide application keys, configures cross-tenant API scopes, sets global expiration guidelines, and revokes compromised tokens immediately. |
| **Security & Compliance Officer** | Audits active API tokens, inspects last-used timestamps to identify stale credentials, enforces 90-day key rotation, and verifies that key hashes meet modern standards. |
| **Integration Developer / DevOps** | Creates tenant-scoped API keys for CRM synchronization (Salesforce, HubSpot), automated billing hooks, webhook receivers, and custom telephony dialer integrations. |
| **Telephony Auditor (Read-Only)** | Reviews active API key inventories, key expiration schedules, and associated descriptions without accessing secret token values. |

---

## 1. Module Overview (Technical)

### What Are API Keys?

API Keys is a **REST API authentication module** that manages tokens for programmatic access to the Ring2All API. Each key can be scoped to specific tenants/domains and optionally have an expiration date.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                API Keys Architecture                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  API Key Definition                                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Key: CRM Integration                          │   │
│  │                                                          │   │
│  │  Key: r2a_xxxx...xxxx (shown once)                      │   │
│  │  Prefix: r2a_                                           │   │
│  │  Scope: Tenant-specific (main)                          │   │
│  │  Domain: All Domains                                     │   │
│  │  Expires: 2025-12-31                                    │   │
│  │  Status: Active                                          │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Used in API requests                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Request                                       │   │
│  │                                                          │   │
│  │  GET /api/v1/extensions                                 │   │
│  │  Authorization: Bearer r2a_xxxx...xxxx                  │   │
│  │  X-Tenant-Slug: main                                    │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Validated by                                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        API Gateway                                       │   │
│  │                                                          │   │
│  │  Checks:                                                 │   │
│  │  ├─ Key exists and active                               │   │
│  │  ├─ Key not expired                                     │   │
│  │  ├─ Tenant scope matches request                        │   │
│  │  └─ Domain scope matches (if restricted)                │   │
│  │                                                          │   │
│  │  Result: Allow or 401 Unauthorized                      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

API Keys provides **secure programmatic access**:

| Without API Keys | With API Keys |
|------------------|---------------|
| No automation | Full API access |
| Manual operations | Scripted workflows |
| No integrations | CRM/ERP integration |
| Password sharing | Secure tokens |

### Use Cases

1. **Third-party Integration**
   - CRM systems
   - Billing platforms
   - Custom dashboards

2. **Automation**
   - Provisioning scripts
   - Bulk operations
   - Scheduled tasks

3. **Multi-tenant Access**
   - Global keys for system integrations
   - Tenant-specific for isolated access

4. **Security Compliance**
   - Expiration policies
   - Key rotation
   - Audit trail

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Secure Keys** | One-time reveal |
| **Tenant Scope** | Global or specific |
| **Domain Scope** | Granular access |
| **Expiration** | Auto-disable old keys |
| **Status Toggle** | Enable/disable |
| **Prefix** | Identify key type |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Create API keys for integrations
- Set tenant scope (global or specific)
- Restrict to specific domains
- Set expiration dates
- Enable/disable keys
- Copy key on creation (one-time)
- Track last usage

### API Keys Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              API Keys                                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [+ Create API Key]                                             │
│                                                                 │
│  [🔍 Search API keys...]                                        │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Name            │ Prefix  │ Scope    │ Expires  │ Status │  │
│  ├─────────────────┼─────────┼──────────┼──────────┼────────┤  │
│  │ CRM Integration │ r2a_abc │ main     │ 2025-12  │ Active │  │
│  │ Billing System  │ r2a_def │ Global   │ Never    │ Active │  │
│  │ Old Script      │ r2a_ghi │ branch   │ 2024-06  │ Expired│  │
│  │ Test Key        │ r2a_jkl │ main     │ Never    │ Inactive│ │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Create API Key

```
┌─────────────────────────────────────────────────────────────────┐
│              Create API Key                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ Basic Information                                            │
│                                                                 │
│  API Key Name: [CRM Integration              ]                 │
│    Unique name for identifying this API key                     │
│                                                                 │
│  Description: [Integration with Salesforce   ]                 │
│    Optional note describing the purpose                         │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Tenant:                                                        │
│  ○ Global (All Tenants)                                        │
│      The API key can access every tenant.                       │
│  ● Tenant-specific                                             │
│      The API key can only access the selected tenant.          │
│                                                                 │
│  Select Tenant: [main ▼]                                       │
│                                                                 │
│  Domain Scope: [All Domains ▼]                                 │
│    When a tenant is selected, you can further restrict         │
│    access to a specific domain.                                 │
│                                                                 │
│  ──────────────────────────────────────────────────────────────│
│                                                                 │
│  Expiration: [2025-12-31    ]                                  │
│    Leave blank for a key without expiration.                    │
│                                                                 │
│  Active: ✓                                                     │
│    Disabled keys are rejected by the API.                       │
│                                                                 │
│  [Create API Key] [Cancel]                                      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Generated Key (Shown Once)

```
┌─────────────────────────────────────────────────────────────────┐
│              🔒 Generated API Key                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  🔒 Your API Key (hover to reveal)                              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ r2a_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0...         [📋]││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
│  ⚠️ Important: This is the only time you will see this API key │
│  in full. Store it securely!                                    │
│                                                                 │
│  Usage: Authorization: Bearer r2a_a1b2c3d4e5f6g7h8...          │
│                                                                 │
│  [Close]                                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Copy Immediately**: Key is shown only once during creation.

> [!TIP]
> **Use Expiration**: Enforce key rotation for security.

> [!WARNING]
> **Store Securely**: Keys cannot be retrieved after creation.

---

## 4. Configuration Sections

### Basic Information

| Field | Description |
|-------|-------------|
| **API Key Name** | Unique identifier |
| **Description** | Purpose notes |
| **Active** | Enable/disable key |

### Scope Settings

| Field | Description |
|-------|-------------|
| **Tenant** | Global or specific tenant |
| **Domain Scope** | All domains or specific |

### Security Settings

| Field | Description |
|-------|-------------|
| **Expiration** | Optional expiration date |

---

## 5. Settings Reference

### Tenant Scope Options

| Option | Description |
|--------|-------------|
| **Global** | Access all tenants |
| **Tenant-specific** | Access one tenant only |

### Status Values

| Status | Description |
|--------|-------------|
| **Active** | Key is valid |
| **Inactive** | Manually disabled |
| **Expired** | Past expiration date |

### API Usage

```bash
# Request with API key
curl -X GET "https://api.ring2all.com/v1/extensions" \
  -H "Authorization: Bearer r2a_your_api_key_here" \
  -H "X-Tenant-Slug: main"
```

---

## 6. Common Scenarios & Examples

### Scenario 1: Create Integration Key

1. Click "Create API Key"
2. Name = "CRM Integration"
3. Description = "Salesforce contact sync"
4. Scope = Tenant-specific, select tenant
5. Expiration = 1 year from now
6. Click Create
7. **Copy the key immediately**
8. Configure in CRM

### Scenario 2: Global System Key

1. Click "Create API Key"
2. Name = "System Automation"
3. Scope = Global (All Tenants)
4. Expiration = None
5. Create and copy key

### Scenario 3: Disable Old Key

1. Find key in list
2. Click Edit
3. Uncheck "Active"
4. Save

### Scenario 4: Key Rotation

1. Create new key (same purpose)
2. Update integration with new key
3. Verify new key works
4. Delete old key

---

## Model Context Protocol (MCP) AI Integration

The Ring2All PBX platform provides Model Context Protocol (MCP) tools for programmatic inspection and audit of external Application Keys.

### MCP Tools Reference

| Tool Name | Operation | Description | Risk Level |
|-----------|-----------|-------------|------------|
| `list_api_keys` | Read | Lists all Application Keys created for external integrations (secret tokens masked for security). | Low |
| `get_api_key_status` | Read | Retrieves metadata, key prefix, creation date, expiration, and last used timestamp for an API Key. | Low |

### JSON Schema Definitions

#### `list_api_keys`
```json
{
  "name": "list_api_keys",
  "description": "Lists all Application Keys created for external machine-to-machine integrations.",
  "parameters": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by API key name or description"
      }
    }
  }
}
```

#### `get_api_key_status`
```json
{
  "name": "get_api_key_status",
  "description": "Retrieves metadata and lifecycle details of a specific Application Key.",
  "parameters": {
    "type": "object",
    "properties": {
      "key_id": {
        "type": "number",
        "description": "Internal numeric API key identifier"
      },
      "name": {
        "type": "string",
        "description": "Application key name or label"
      }
    }
  }
}
```

### Natural Language Prompt Examples

#### English
- *"List all active application keys and their expiration dates."*
- *"Check the last time the 'CRM_Salesforce_Prod' API key was used."*
- *"Are there any API keys that have already expired or are expiring within 7 days?"*

#### Spanish
- *"Muestra todas las llaves de aplicación activas y sus fechas de vencimiento."*
- *"Verifica cuándo fue el último uso de la llave de API 'Integracion_Facturacion'."*
- *"¿Hay alguna llave de aplicación expirada o inactiva en el sistema?"*

### Enterprise Safeguards & Guardrails
1. **Strict Token Masking**: Full API secrets are shown once at creation and never exposed in MCP tool responses.
2. **Read-Only Inspection**: AI tools allow inspection and auditing of key metadata without exposing capability to regenerate or leak credentials.
3. **Tenant Boundary Enforcement**: Key listings are strictly partitioned by the requesting tenant ID.

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **One-time Display**: Key shown only at creation.

> [!NOTE]
> **Cannot Retrieve**: Lost keys require new key creation.

> [!WARNING]
> **Secure Storage**: Store keys in secure credential managers.

### Best Practices

1. **Unique Keys**: One key per integration
2. **Descriptive Names**: "CRM_Salesforce_Prod"
3. **Set Expiration**: Enforce rotation
4. **Least Privilege**: Tenant-specific when possible
5. **Rotate Regularly**: Replace keys periodically

### Security Recommendations

| Practice | Description |
|----------|-------------|
| **Key Rotation** | Replace keys every 90 days |
| **Environment Vars** | Don't hardcode keys |
| **Audit Usage** | Monitor last used dates |
| **Disable Unused** | Deactivate unused keys |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| 401 Unauthorized | Key inactive | Check status |
| 401 Unauthorized | Key expired | Create new key |
| 403 Forbidden | Wrong tenant | Check scope |
| Key lost | Not saved | Create new key |

### Test API Key

```bash
# Verify key works
curl -I "https://api.ring2all.com/v1/health" \
  -H "Authorization: Bearer r2a_your_key"

# Expected: HTTP 200 OK
```

### Check Key in Database

```sql
SELECT 
  name,
  prefix,
  tenant_scope,
  is_active,
  expires_at,
  last_used_at
FROM public.api_keys
WHERE name = 'CRM Integration';
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **API Key** | Authentication token |
| **Bearer Token** | Authorization header format |
| **Tenant Scope** | Access restriction |
| **Prefix** | Key identifier (r2a_) |
| **Expiration** | Auto-disable date |
| **Key Rotation** | Regular key replacement |

---

*Documentation last updated: January 2026*