---
title: "Authorization Codes Module Documentation"
description: "Documentation for Authorization Codes"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
4. [Configuration Fields Reference](#4-configuration-fields-reference)
5. [Call Flow / Logic Explanation](#5-call-flow--logic-explanation)
6. [Import/Export Feature](#6-importexport-feature)
7. [Common Scenarios & Examples](#7-common-scenarios--examples)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Limitations & Important Notes](#9-limitations--important-notes)
10. [Troubleshooting Tips](#10-troubleshooting-tips)
11. [Glossary](#11-glossary)
---

## 1. Module Overview (Technical)

### What Are Authorization Codes?

Authorization Codes allow users to **temporarily elevate their Class of Service (CoS)** for a single call. By entering a valid authorization code, users gain access to dial destinations normally restricted by their assigned CoS.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│              Authorization Code System                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  User dials feature code *79 (Authorization Code)               │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Feature Code Validation                     │   │
│  │  Check: Is user's CoS allowed to use *79?               │   │
│  │  ├─ NO → "Feature not allowed" → Hangup                 │   │
│  │  └─ YES → Continue                                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Code Entry                                  │   │
│  │  Play: "Enter your authorization code"                   │   │
│  │  User enters: 5678#                                      │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Validation                                  │   │
│  │  SELECT cos_id FROM public.authorization_codes           │   │
│  │  WHERE code = '5678' AND active = TRUE                   │   │
│  │                                                          │   │
│  │  ├─ Found → Apply CoS override                          │   │
│  │  └─ Not found → "Invalid code" → Hangup                 │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Set channel variable: override_cos_id = [elevated CoS ID]      │
│  Play: "Authorization successful"                               │
│  Return dial tone for outbound call                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## 🎯 User Roles & Key Capabilities

| Role | Key Capabilities & Permissions |
|------|--------------------------------|
| **Super Admin** | System-wide policy governance; configure authentication thresholds and audit authorization code generation across all PBX tenants. |
| **Tenant Admin** | Provision, import, export, and manage Authorization Codes; link codes to elevated Class of Service tiers and assign privacy aliases for CDR reports. |
| **PBX Operator** | Monitor code usage, verify active PIN authorizations, and track CDR events mapped to specific authorization code aliases. |
| **End User** | Dials the feature code (*79), enters their assigned Authorization Code followed by `#`, and unlocks elevated calling destinations for their active session. |

---

## 2. Module Overview (Commercial/Business)

### Business Value

Authorization Codes enable **controlled access** to restricted destinations:

| Without Auth Codes | With Auth Codes |
|-------------------|-----------------|
| Permanent CoS changes | Temporary elevation |
| IT involvement needed | User self-service |
| No accountability | Code-based tracking |
| All or nothing access | Per-call authorization |

### Use Cases

1. **International Calling**
   - Normal users have domestic-only CoS
   - Managers have international auth codes
   - One-time international calls without CoS change

2. **Toll-Free/Premium Bypass**
   - Default CoS blocks premium numbers
   - Auth codes allow approved calls

3. **Guest/Temporary Access**
   - Contractors with limited CoS
   - Auth codes for specific project needs

4. **Audit Trail**
   - Track who used which code
   - CDR includes alias for billing

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Per-Code CoS** | Different codes = different permissions |
| **Alias in CDR** | Replaces code in call records |
| **Import/Export** | Bulk management via CSV |
| **Active Toggle** | Enable/disable without deletion |
| **Multi-tenant** | Separate codes per domain |

---

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

### What Can You Do?

- Create authorization codes with CoS assignments
- Set aliases for CDR identification and PIN masking
- Import/export codes via CSV
- Enable/disable codes without deletion

### Navigation

1. Navigate to **PBX Engine → Class of Services → Authorization Codes** in the main navigation menu.
2. The **list view** displays all configured authorization codes with Code, Alias, Description, assigned Class of Service, and active status.
3. Click the **+ Add** button in the top toolbar to create a new authorization code profile.
4. Click any code row or edit action to adjust PIN digits, alias, description, or target Class of Service.

![Authorization Codes List View](/screenshots/pbx/class-of-service/authorization-codes-list.png)

### Administrator Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│              Creating an Authorization Code                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Code Information                                       │
│  ├─ Authorization Code: 74921                                   │
│  ├─ Alias: "Executive Override PIN" (appears in CDR)            │
│  └─ Description: "Temporary VIP privilege elevation"            │
│                                                                 │
│  Step 2: Class of Service                                       │
│  └─ Select: "Default" (or Executive CoS)                       │
│                                                                 │
│  Step 3: Enable and Save                                        │
│                                                                 │
│  Result: Users entering 74921 get target CoS permissions        │
│          for that call only                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### User Workflow (Using Auth Code)

```
1. User dials *79 (Authorization Code feature)
2. System: "Enter your authorization code"
3. User enters: 74921#
4. System: "Authorization successful"
5. User dials destination number
6. Call connects with elevated CoS permissions
```

### Quick Tips

> [!TIP]
> **Use Aliases**: Set meaningful aliases for CDR tracking (e.g., "Executive Override PIN", "SalesMgr"). The alias protects the secret PIN from exposure in billing reports.

> [!TIP]
> **Code Complexity**: Use at least 4 to 6 numeric digits to prevent brute-force guesswork.

> [!CAUTION]
> **Code Sharing**: Shared codes diminish auditability and individual accountability. Rotate codes periodically.

---

## 4. Configuration Fields Reference

![Authorization Code Configuration Form](/screenshots/pbx/class-of-service/authorization-codes-form.png)

### Basic Information Fields

| Field | Description | User-Friendly Tooltip | Example | Notes |
|-------|-------------|----------------------|---------|-------|
| **Code \*** | Numeric authorization PIN or password | Secret numeric code entered by callers to elevate permissions | `74921`, `5678` | Required. Unique per domain. |
| **Alias** | Safe identifier recorded in Call Detail Records (CDR) | Human-readable alias logged in CDRs to mask the secret PIN | `Executive Override PIN` | Highly recommended. Prevents PIN exposure in billing records. |
| **Description** | Contextual notes and operational scope | Purpose or user group authorized to use this PIN | `Temporary VIP privilege elevation for field staff` | Optional. |
| **Class of Service \*** | Elevated permission profile applied upon verification | Class of Service granted for the duration of the call | `Executive`, `Default` | Required. Controls ARS routes, dial restrictions, and feature permissions. |
| **Active \*** | Operational status of the authorization code | Toggle whether this authorization code is currently valid | `Toggle (On/Off)` | Required. Inactive codes are rejected by the telephony IVR. |

### CDR Behavior

When a call uses an authorization code:
- **Without Alias**: CDR displays the raw code (`74921`).
- **With Alias**: CDR displays the masked alias text (`Executive Override PIN`).

---

## 5. Call Flow / Logic Explanation

### Authorization Code Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                 Authorization Code Flow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. User dials *79                                              │
│     │                                                           │
│     ▼                                                           │
│  2. Check if *79 is allowed for user's CoS                      │
│     ├─ Allowed → Continue                                      │
│     └─ Not allowed → "Feature not allowed" → Hangup            │
│     │                                                           │
│     ▼                                                           │
│  3. Prompt for authorization code                               │
│     │                                                           │
│     ▼                                                           │
│  4. User enters code (e.g., 5678#)                              │
│     │                                                           │
│     ▼                                                           │
│  5. Validate code against database                              │
│     SELECT cos_id FROM public.authorization_codes              │
│     WHERE code = '5678' AND active = TRUE                      │
│     │                                                           │
│     ├─ Found → Continue                                        │
│     └─ Not found → "Invalid code" → Hangup                     │
│     │                                                           │
│     ▼                                                           │
│  6. Set channel variable: override_cos_id                       │
│     │                                                           │
│     ▼                                                           │
│  7. Play success confirmation                                   │
│     │                                                           │
│     ▼                                                           │
│  8. User dials destination number                               │
│     │                                                           │
│     ▼                                                           │
│  9. Outbound routing uses override_cos_id                       │
│     (elevated permissions for this call only)                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Channel Variables

| Variable | Description |
|----------|-------------|
| `override_cos_id` | Temporary CoS ID applied to call |

---

## 6. Import/Export Feature

### CSV Export

**Purpose**: Backup codes or migrate to another system.

**Format**:
```csv
code,alias,description,classOfService,active
5678,SalesMgr,For sales international calls,International Access,true
1234,Guest,Guest access code,Standard,true
9012,Emergency,Emergency bypass,Full Access,true
```

### CSV Import

**Import Modes**:

| Mode | Behavior |
|------|----------|
| **Skip existing** | Keep current codes, skip duplicates |
| **Update existing** | Update alias/description/active if code exists |
| **Replace all** | Delete all and import fresh |

**Required Columns**:
- `code` - The authorization code
- `alias` - CDR replacement text
- `description` - Admin notes
- `classOfService` - CoS name (must exist)
- `active` - true/false

---

## 7. Common Scenarios & Examples

### Scenario 1: International Access for Managers

**Setup:**
| Code | Alias | CoS |
|------|-------|-----|
| 8888 | MgrIntl | International Access |

**Usage**: Manager dials *79 → enters 8888 → dials +44...

### Scenario 2: Project-Based Codes

**Setup:**
| Code | Alias | CoS | Description |
|------|-------|-----|-------------|
| 1001 | ProjectAlpha | Long Distance | Alpha team |
| 1002 | ProjectBeta | Long Distance | Beta team |

**Tracking**: CDR shows "ProjectAlpha" or "ProjectBeta" for billing.

### Scenario 3: Emergency Override

**Setup:**
| Code | Alias | CoS |
|------|-------|-----|
| 9999 | EmergencyOverride | Full Access |

**Usage**: In emergencies, users can dial any number.

## 8. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Authorization Codes**, allowing autonomous AI agents and Copilots to query authorization PIN privileges, inspect unlocked Class of Service profiles, and provision or update override codes with domain-level isolation and uniqueness enforcement.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_authorization_codes` | Lists all authorization codes configured in the domain, including PIN values, friendly aliases, linked Class of Service profiles, and active status. | `search` (optional string) |
| `get_authorization_code_status` | Retrieves full configuration, alias, and unlocked Class of Service for a specific authorization code. | `code` (required) |
| `create_authorization_code` | Provisions a new authorization code PIN that unlocks an elevated Class of Service profile. | `code`, `classOfServiceName`, `alias`, `description`, `active` |
| `update_authorization_code` | Modifies an existing authorization code PIN, target Class of Service, alias, or active status. | `code`, `newCode`, `classOfServiceName`, `alias`, `description`, `active` |
| `delete_authorization_code` | Deletes an authorization code from the domain. | `code` (required) |

### Strict Domain Uniqueness & Safeguards
Whenever `create_authorization_code` or `update_authorization_code` is executed, Ring2All verifies that the authorization code value is strictly unique within the domain (`public.authorization_codes`). An authorization code cannot be duplicated across users or departments in the same tenant.

### AI Agent Operational Examples

#### Querying Authorization Codes
```json
{
  "tool": "list_authorization_codes",
  "arguments": {
    "search": "Executive"
  }
}
```

#### Provisioning an Emergency Privilege Override Code
```json
{
  "tool": "create_authorization_code",
  "arguments": {
    "code": "8492",
    "classOfServiceName": "Executive Full Access",
    "alias": "Director Roaming Override",
    "description": "Allows directors to bypass outbound restrictions on lobby phones",
    "active": true
  }
}
```

### Recommended Natural Language Prompts
- *"List all authorization codes and which Class of Service each code unlocks."*
- *"Create an authorization code '7744' linked to the 'International Access' Class of Service with alias 'Marketing VP'."*
- *"Deactivate authorization code '8492' without deleting it."*

---

## 9. Limitations & Important Notes

### Technical Limitations

> [!WARNING]
> **Single Call Only**: Authorization applies to the next call only, not permanent.

> [!WARNING]
> **Feature Code Required**: Users must dial *79 first—cannot be automatic.

### Best Practices

1. **Unique Codes**: Assign unique codes per user/purpose
2. **Meaningful Aliases**: Use aliases for CDR clarity
3. **Regular Audits**: Review code usage periodically
4. **Strong Codes**: Use 4+ digits, avoid patterns
5. **Disable vs. Delete**: Disable for temporary revocation

### Security Considerations

> [!CAUTION]
> **Code Secrecy**: Treat authorization codes like passwords.

---

## 10. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| "Feature not allowed" | *79 not in user's CoS | Enable *79 in feature codes |
| "Invalid code" | Code not found/disabled | Check code exists and is active |
| Still restricted | override_cos_id not honored | Check routing respects override |
| No prompt heard | Audio file missing | Check enter_auth_code.wav |

### Diagnostic SQL

**List authorization codes:**
```sql
SELECT ac.code, ac.alias, ac.active,
       cos.name as class_of_service
FROM public.authorization_codes ac
JOIN public.class_of_services cos ON ac.cos_id = cos.id
WHERE ac.domain_id = [domain_id];
```

**Check code usage (if logged):**
```sql
-- Check CDR for authorization code usage
SELECT * FROM public.cdr
WHERE authorization_code IS NOT NULL
ORDER BY call_start DESC
LIMIT 50;
```

---

## 11. Glossary

| Term | Definition |
|------|------------|
| **Authorization Code** | Numeric code that temporarily elevates CoS |
| **CoS Elevation** | Temporarily granting higher permissions |
| **override_cos_id** | Channel variable with elevated CoS ID |
| **Alias** | Text that replaces code in CDR |
| **Feature Code** | *79 - the dialpad code to invoke authorization |

---

*Documentation last updated: January 2026*