Treat a PIN Set as one route-stage gate
Sangoma documents the standard PIN Sets module as a way to maintain lists of numeric passwords and associate one list with an outbound route. When the route is selected, FreePBX can prompt the caller and compare the entry with that set before the call continues. This is one stage in a larger path: dialed-digit normalization, outbound-route order, PIN acceptance, trunk selection, provider policy, answer and media remain separate evidence.
A configured set does not prove the intended route matched, and a successful PIN does not prove the provider accepted the call. Define the protected destinations, permitted callers, route order and expected rejection result before making the change. Do not use a shared route PIN as proof of a person's identity, a substitute for extension permissions or an accounting control with no independent review.
Confirm the installed module before following the older guide
The detailed Sangoma PIN Sets and outbound-route guides are explicitly labelled for PBX GUI 13. The FreePBX repository currently has a release/17.0 PIN Sets branch whose module metadata lists version 17.0.4 and support for FreePBX 17. Confirm the installed module version, signature and enabled state through the supported Module Administration workflow; a repository branch does not prove that version is installed on a particular PBX.
The 17.0.4 metadata includes a security-related changelog entry. Treat that as a reason to compare the installed signed package with the current supported channel, not as proof that an uninspected host is vulnerable or repaired. Preserve the module, Core and FreePBX versions in the change record and use the installed interface labels as the local source of truth.
Build the set without turning it into a credential leak
Use a descriptive set name and one numeric PIN per line as documented, but choose values under the organization's credential policy rather than the public examples. Do not reuse voicemail, portal, device-admin or provider credentials. Limit who can view or change the list, avoid screenshots containing PINs and redact them from tickets, chat, captures and test notes.
Assign a lifecycle owner, expiry or rotation trigger and revocation process. Shared PINs provide weaker attribution than per-user controls because knowledge can spread without a change to the calling extension. If the requirement is individual accountability, entitlement by extension or richer reporting, evaluate a control designed for that purpose instead of overstating what the standard module proves.
Attach the set to the exact outbound route
Sangoma's version-13 guide places the PIN Set selection in an outbound route's additional settings, with None as the default. Before linking it, record the route's position, patterns, prefixes, time controls and trunk sequence. FreePBX evaluates outbound routes in order, so a broader earlier route can carry the call without ever reaching the protected route.
Submit and Apply Config are distinct documented actions. After applying, inspect the generated and loaded dialplan through supported tools and prove that an allowed destination selects the protected route. Do not edit generated files as the durable repair, duplicate routes casually to work around policy, or add a PIN gate to emergency calling without the responsible emergency-program owner and provider validating the complete design.
Decide whether the entered PIN may enter CDR data
The standard module exposes a “Record in CDR” choice, and Sangoma documents that an entered PIN can be placed in the CDR accountcode field. That can aid route-level correlation, but it also converts a reusable secret into reporting data. Inventory every CDR reader, export, backup, API, retention job and downstream billing or analytics consumer before enabling it.
Do not assume an accountcode identifies a unique human, and do not publish raw PINs in reports. Prefer a non-secret identifier where the business requirement permits it. If recording is required, document access, masking, retention and rotation, then verify that unauthorized report users and exports do not expose the credential.
Test route match, prompt, denial and completion separately
Use bounded authorized tests: one allowed destination with a valid PIN, the same route with an invalid PIN, an intentionally unprotected route, overlap with a broader route and any time-based path that can change route availability. Record the caller, dialed digits, selected route, prompt, acceptance or denial, attempted trunk, provider response and final answer separately.
Keep the previous route and set configuration for rollback. After a PIN change or removal, prove that the old value fails, the intended new value succeeds and unrelated routes remain unchanged. Remove captures and test artifacts promptly. No PIN, route, CDR, trunk, provider response or call was tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Sangoma FreePBX standard PIN Sets module ↗
- Sangoma FreePBX PIN Sets admin guide (PBX GUI 13) ↗
- Sangoma FreePBX outbound routes guide (PBX GUI 13) ↗
- FreePBX PIN Sets release/17.0 module metadata ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.