Configure Token Authentication Header (X-Telnyx-Token) in FreePBX

Add a Telnyx token-based authentication header to outbound SIP calls from your FreePBX PBX system. See Telnyx guidance and requirements.

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

1. Calls are authenticated using IP for setups explicitly using IP Auth.
2. No token is included in SIP INVITEs by default.

New Behavior (With Token Header)

1. FreePBX injects an X-Telnyx-Token header in every outbound INVITE.
2. 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:

1. Access the Asterisk console:

   asterisk -rvv
   

2. Enable SIP debugging:

   sip set debug on
   

3. Place an outbound call.

4. 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.conf before editing.

---

References

• Telnyx SIP Connection Setup Guide
• Telnyx Trunk with FreePBX V15 Configuration