Authorization Codes Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Call Flow / Logic Explanation
Import/Export Feature
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
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

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              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                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.authorization_codes`	Code definitions with CoS mapping
`public.class_of_services`	Referenced CoS for elevation

Key Files

File	Description
`admin/apps/web/src/modules/authorizationCodes/`	Frontend module
`admin/apps/web/src/i18n/en/authorizationCodes.json`	Translations
`telephony/freeswitch/lua/features/authorization_code.lua`	Handler

---

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

International Calling

- Normal users have domestic-only CoS

- Managers have international auth codes

- One-time international calls without CoS change

Toll-Free/Premium Bypass

- Default CoS blocks premium numbers

- Auth codes allow approved calls

Guest/Temporary Access

- Contractors with limited CoS

- Auth codes for specific project needs

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
Import/export codes via CSV
Enable/disable codes

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Creating an Authorization Code                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Code Information                                       │
│  ├─ Authorization Code: 5678                                   │
│  ├─ Alias: "Sales Intl" (appears in CDR)                       │
│  └─ Description: "International for sales team"                │
│                                                                 │
│  Step 2: Class of Service                                       │
│  └─ Select: "International Access" CoS                         │
│                                                                 │
│  Step 3: Enable and Save                                        │
│                                                                 │
│  Result: Users entering 5678 get "International Access" CoS    │
│          for that call only                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Workflow (Using Auth Code)

Plaintext

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

Quick Tips

TIP

Use Aliases: Set meaningful aliases for CDR tracking (e.g., "ProjectX", "SalesMgr").

TIP

Code Complexity: Use at least 4 digits for security.

CAUTION

Code Sharing: Shared codes lose individual accountability.

---

4. Configuration Fields Reference

Authorization Code Fields

Field	Description	Example	Required
Authorization Code	The code users enter	`5678`	Yes
Alias	CDR replacement text	`SalesMgr`	No
Description	Admin notes	`For sales intl calls`	No
Class of Service	CoS to apply	`International Access`	Yes
Active	Code enabled status	On/Off	Yes

CDR Behavior

When a call uses an authorization code:

Without Alias: CDR shows raw code (5678)
With Alias: CDR shows alias text (SalesMgr)

---

5. Call Flow / Logic Explanation

Authorization Code Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 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

Code	Alias	CoS	Description
1001	ProjectAlpha	Long Distance	Alpha team
1002	ProjectBeta	Long Distance	Beta team

Code	Alias	CoS
9999	EmergencyOverride	Full 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. 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

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

Security Considerations

CAUTION

Code Secrecy: Treat authorization codes like passwords.

---

9. 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;

---

10. 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

---

Lua Script Status ✅

Integration Module

Component	Status	Location
Auth Codes Handler	✅ Active	`app/authorization_codes/auth_codes.lua`

---

Documentation last updated: January 2026*

Authorization Codes Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Authorization Codes?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

User Workflow (Using Auth Code)

Quick Tips

4. Configuration Fields Reference

Authorization Code Fields

CDR Behavior

5. Call Flow / Logic Explanation

Authorization Code Flow

Channel Variables

6. Import/Export Feature

CSV Export

CSV Import

7. Common Scenarios & Examples

Scenario 1: International Access for Managers

Scenario 2: Project-Based Codes

Scenario 3: Emergency Override

8. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

9. Troubleshooting Tips

Common Issues

Diagnostic SQL

10. Glossary

Lua Script Status ✅

Integration Module