SIP trunks
A SIP trunk connects your phone system to Bird. It gives your PBX an address for outbound calls and defines how Bird authenticates them. Configure trunks under Voice > SIP Trunks.
Most workspaces need one trunk. Create separate trunks when sites or systems need different IP allow lists, API keys, session-credential settings, or Digest algorithms.
Create a trunk
Select Create trunk and enter a name. You can change this dashboard label later; it is not sent with calls.
Bird assigns a fixed SIP domain to the trunk. Enter this domain in your phone system so Bird can associate calls with the trunk.
A new trunk turns away every call until you tell it who may place them: an IP range, an API key, session credentials, or a combination.
Call direction
A new trunk does not carry calls. Under Outbound calling, select Enable outbound. Until enabled, the trunk refuses every outbound attempt regardless of its credentials.
The trunk page groups its connection details, allow lists, keys, session credentials, and Digest offer under Outbound calling.
Connection details
Open a trunk to see what to enter into your PBX:
| Setting | Value |
|---|---|
| SIP domain | The trunk's own domain. Copy it whole from the trunk page |
| Username | Always bird, on every trunk and every workspace |
| Password | The secret of an API key allowed on this trunk (see API key authentication) |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.
Send your calls to the SIP domain on one of these ports:
| Transport | Port | Notes |
|---|---|---|
| UDP | 5060 | The default most equipment assumes |
| TCP | 5060 | Same port as UDP, so pick the transport on your PBX |
| TLS | 5061 | SIP over TLS, for signaling you want encrypted in transit |
Controlling who may send calls
A trunk can authenticate equipment by source IP address, API key, or a short-lived session credential. Enable the methods your clients need.
Configure them in IP allow list, Allowed API keys, and Session credentials. Saved changes apply to new calls.
IP allow list
Add the public addresses your equipment sends SIP from, as single addresses or CIDR ranges, each with an optional description. IP filtering becomes active the moment the list has one entry: from then on, only listed ranges may send calls to this trunk.
Add the public source address that reaches Bird. For equipment behind NAT, use the router's public address instead of the phone system's private address. Bird refuses calls from unlisted addresses at the SIP layer, so they usually do not reach the call log. See voice troubleshooting for missing calls.
API key authentication
Bird can instead (or also) ask each call for a password. The exchange is SIP Digest authentication: Bird sends a challenge, your phone system answers with a hash of the password rather than the password itself, and Bird verifies it against a Bird API key.
- Give an API key the voice permission at write level, which is the level a trunk authenticates against. Add it to a key you already have, or create a new one. Either way the key's secret works unchanged: a key you already deployed keeps the secret your systems are configured with, and a new key shows its secret once, at creation, so save it then. See API keys.
- On the trunk page, under Allowed API keys, add that key.
- In your PBX, set the username to bird and the password to the key's secret.
API-key authentication becomes active the moment the list has one key: from then on, only the keys you list may authenticate.
Taking the voice permission off a key stops it authenticating straight away, but the trunk keeps it in the allowed list. Add the permission back and the trunk works again with the same secret, with nothing to change on the trunk or in your PBX. While the permission is missing, the trunk page marks that key so the allowed list never reads as working when it is not.
Revoking or deleting an API key removes its ability to authenticate immediately, on every trunk that allowed it, and that one is permanent. Rotate by adding the new key to the trunk first, moving your equipment over, then revoking the old one.
Session credentials
A session credential is a short-lived SIP username and password. It answers the same Digest challenge as an API key without exposing a long-lived secret.
Turn them on under Session credentials on the trunk page; they are off on a new trunk. What they admit:
- The phone in the dashboard, which mints one per call for you.
- A SIP client driven by the CLI: bird voice tools test-call mints one for the call it places, and bird voice session-credentials create mints one to paste into any other client. Both need voice access at write level.
A credential belongs to the workspace rather than one trunk, so a client can use it across eligible trunks. The client must present the credential, and the trunk must have session credentials enabled. Bird returns the password only when minting it.
Turning them on does not change how equipment on the IP allow list connects: a call from a listed address, on a trunk with no allowed API keys, is still admitted without a password challenge.
Digest algorithm
By default, Bird offers SHA-256 first and MD5 second. Your PBX answers with the first algorithm it supports.
Change the offer under Digest algorithm when your equipment requires it. For a PBX that mishandles a challenge beginning with SHA-256, select MD5 only. A trunk accepts only the algorithms it offers. API keys work with either algorithm and do not need to be reissued.
Keep MD5 in the offer on any trunk you call from the phone: a browser answers with MD5 and nothing else, so a trunk offering only SHA-256 rejects every browser call.
Delete a trunk
Deleting a trunk takes effect at once: its SIP domain stops accepting new calls. Calls already in progress continue, and the call records made through the trunk stay in your Call log.
Next steps
| Page | What it covers |
|---|---|
| Place your first call | From an empty workspace to a ringing phone |
| Phone | Calling from the dashboard, over a trunk that takes session credentials |
| Placing calls | What Bird expects on the INVITE, and what a call costs |
| Caller IDs | Registering a number and proving you own it with a verification call |
| API keys | Creating a key, choosing its scopes, and rotating it |