Authentication Codes Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Code Management
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Authentication Codes?

Authentication Codes are inbound call authentication rules that require callers to enter a valid PIN/code before routing to a destination. If authentication fails, calls are routed to a fail destination.

IMPORTANT

Not to be confused with Authorization Codes!

Authentication Codes: PIN-protect inbound calls (caller must enter code)
Authorization Codes: Account codes for outbound call billing

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│               Authentication Code Flow                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Inbound Call arrives at Authentication Rule                    │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           Authentication Handler                         │   │
│  │                                                          │   │
│  │  1. Play prompt: "Please enter your access code"        │   │
│  │  2. Collect DTMF digits                                  │   │
│  │  3. Validate code against public.authentication_codes   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ├── Valid Code? ─────────────────────────────────────►    │
│       │       Yes → Route to Match Destination                 │
│       │             (e.g., VIP Extension)                      │
│       │                                                         │
│       └── Invalid or Max Attempts ─────────────────────────►    │
│               Route to Fail Destination                         │
│               (e.g., Main IVR, Hangup)                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.authentication_rules`	Authentication rule configurations
`public.authentication_codes`	Valid codes for each rule

Key Files

File	Description
`admin/apps/web/src/modules/authenticationCodes/`	Frontend module
`admin/apps/web/src/i18n/en/authenticationCodes.json`	Translations

---

2. Module Overview (Commercial/Business)

Business Value

Authentication Codes enable access-controlled inbound routing:

Without Authentication	With Authentication
Open access	PIN-protected
Anyone can reach VIP line	Only authorized callers
No security	Verified access
No tracking	Usage logging

Use Cases

VIP Line Protection

- Partners enter PIN to reach VIP support

- Invalid: routed to public queue

After-Hours Access

- Employees enter code for after-hours access

- Invalid: routed to voicemail

Restricted Services

- PIN to access conference bridge

- Invalid: connection refused

Private Direct Lines

- High-security executives

- PIN-protected access

Feature Highlights

Feature	Benefit
Multiple Codes	Different codes per rule
Code Labels	Track who's using which code
Max Attempts	Limit failed attempts
Timeout Control	Entry time limit
Match/Fail Routing	Dual destination
CSV Import	Bulk code management
Usage Tracking	Count per code

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create authentication rules
Add multiple valid codes per rule
Set match destination (valid code)
Set fail destination (invalid/timeout)
Configure timeout and max attempts
Import codes from CSV
Track code usage

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│           Creating an Authentication Rule                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Tab: Rule                                                      │
│  ├─ Name: "VIP Line Access"                                    │
│  ├─ Description: "PIN access for VIP partners"                 │
│  ├─ Context: auth_vip_line (auto-generated)                    │
│  ├─ Instructions Message: [Select] "enter_access_code.wav"     │
│  ├─ Timeout: 10 seconds                                        │
│  ├─ Max Attempts: 3                                            │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Section: Destinations                                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ When Match:                                               │  │
│  │ ├─ Destination Type: Extension                            │  │
│  │ └─ Destination: VIP Support (1001)                        │  │
│  └───────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ When Fail:                                                │  │
│  │ ├─ Destination Type: IVR                                  │  │
│  │ └─ Destination: Main Menu                                 │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Tab: Codes                                                     │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Code     │ Label           │ Enabled │ Used          │    │  │
│  ├──────────┼─────────────────┼─────────┼───────────────┤    │  │
│  │ 1234     │ Partner A       │   ✓     │ 47            │    │  │
│  │ 5678     │ Partner B       │   ✓     │ 23            │    │  │
│  │ 9999     │ Internal Test   │   ✗     │ 0             │    │  │
│  └───────────────────────────────────────────────────────────┘  │
│  [Add Code] [Import from CSV]                                   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Use Labels: Add labels to codes to track who's using them.

TIP

CSV Import: Bulk import codes using CSV file.

CAUTION

Unique Codes: Codes must be unique within each rule.

---

4. Configuration Fields Reference

Rule Fields

Field	Description	Example
Name	Rule identifier	`VIP Line Access`
Description	Optional notes	`PIN for partners`
Context	Dialplan context	`auth_vip_line`
Instructions Message	Audio prompt	`enter_code.wav`
Timeout	Entry timeout (seconds)	10
Max Attempts	Failed attempt limit	3
Enabled	Rule active	On/Off

Destination Fields

Field	Description
Match Destination Type	Module when code valid
Match Destination Data	Target when code valid
Fail Destination Type	Module when code invalid
Fail Destination Data	Target when code invalid

Destination Types

Type	Description
Extension	Route to extension
Voicemail	Route to voicemail
IVR	Route to IVR menu
Conference	Route to conference
Queue	Route to call queue
Hangup	Terminate call
Announcement	Play announcement

Code Fields

Field	Description
Code	PIN to enter
Label	Friendly name
Enabled	Code active
Used Count	Usage tracking

---

5. Code Management

Adding Codes

Go to Codes tab
Click Add Code
Enter code (PIN) and optional label
Save

CSV Import

Import multiple codes from CSV file:

CSV Format:

Csv

code,label,enabled
1234,Partner A,true
5678,Partner B,true
9999,Internal Test,false

Import Modes:

Mode	Description
Skip Existing	Keep existing codes unchanged
Update Existing	Update existing codes with new data
Replace All	Delete all and import fresh

Usage Tracking

Each code tracks usage count to monitor:

Which codes are most used
Inactive codes to disable
Partner usage patterns

---

6. Common Scenarios & Examples

Scenario 1: VIP Partner Access

Rule: "VIP Partner Line"

Setting	Value
Prompt	"Please enter your partner access code"
Timeout	10 seconds
Max Attempts	3
Match →	VIP Support Extension
Fail →	Main IVR

Codes:

Code	Label
1234	Partner ABC
5678	Partner XYZ

Scenario 2: After-Hours Employee Access

Rule: "After-Hours Access"

Setting	Value
Prompt	"Enter your employee PIN"
Timeout	8 seconds
Max Attempts	2
Match →	Night Queue
Fail →	Voicemail

Scenario 3: Conference PIN

Rule: "Conference Auth"

Setting	Value
Prompt	"Enter conference access code"
Timeout	15 seconds
Max Attempts	3
Match →	Conference Bridge
Fail →	Hangup

---

7. Limitations & Important Notes

Technical Notes

NOTE

Match First: First matching code wins (order doesn't matter for codes).

WARNING

Timeout Impacts: Too short timeout may cause false failures.