Background
When sending calls from a private PBX to Telnyx via IP-based SIP trunks, you can authenticate those calls using a connection token.
This is done by adding a custom SIP header — X-Telnyx-Token — to each outbound SIP INVITE.
Telnyx validates this token against the configured SIP connection in your account.
Standard Behavior
Calls are authenticated using IP for setups explicitly using IP Auth.
No token is included in SIP INVITEs by default.
New Behavior (With Token Header)
FreePBX injects an
X-Telnyx-Tokenheader in every outbound INVITE.Telnyx verifies the token and authorizes the call.
Note: This setup assumes there’s only one IP-based trunk. If multiple IP trunks exist, the header will be added to all unless scoped to the target connection in the macro.
Pre-requisites
Before starting, ensure you have:
A Telnyx SIP Connection set up for outbound calls.
Your Telnyx Connection Token (from the Telnyx Mission Control Portal).
Admin or root access to your FreePBX system.
Permission to edit Asterisk configuration files.
Step 1: Locate the Custom Extensions config File
FreePBX stores custom user-defined contexts in:
/etc/asterisk/extensions_custom.conf
This file allows you to extend dialplan behavior safely without affecting system updates.
Step 2: Add the Token Authentication Macro
Open /etc/asterisk/extensions_custom.conf in a text editor and append the following:
[macro-dialout-trunk-predial-hook]
exten => s,1,NoOp(Entering user defined context [macro-dialout-trunk-predial-hook] in extensions_custom.conf)
same => n,GoSub(func-set-sipheader,s,1(X-Telnyx-Token,TOKENFROMPORTAL)) same => n,Verbose(2,Added X-Telnyx-Token universally)
same => n,MacroExit()
Replace TOKENFROMPORTAL with your actual token from the Telnyx Portal.
Step 3: Apply and Reload Configuration
After saving changes, apply them with:
fwconsole reload
This reloads the Asterisk dialplan without restarting services.
Step 4: Verify the Header
To confirm the header is applied correctly:
Access the Asterisk console:
asterisk -rvv
Enable SIP debugging:
sip set debug on
Place an outbound call.
In the INVITE request, look for:
X-Telnyx-Token: TOKENFROMPORTAL
Tips for Success
Validate the token in the Telnyx Portal before applying.
Scope logic carefully if multiple IP trunks exist.
Backup
extensions_custom.confbefore editing.