# SIP ACL

> How the workspace registrar access control list admits inbound SIP signalling, how entries are matched, and how trunk peers relate to it.

The **SIP ACL** is the workspace-level allow list that the TeleQuick
registrar consults before it accepts inbound SIP signalling from an
address that is not a configured trunk peer. It is an admission control,
not a routing rule: it decides whether a packet is allowed to reach the
registrar and the dialplan at all.

You manage it on the **SIP ACL** screen in the admin console.

## What the ACL controls

The ACL guards the registrar's signalling surface for the workspace. It
applies to inbound SIP traffic that arrives from an address TeleQuick
does not already recognise as a trunk peer — PBXs, session border
controllers, softphones, and test tools that talk directly to the
registrar.

It is an *allow* list. An address that is not covered by an entry and is
not a configured trunk peer is not admitted, so the request never
reaches trunk lookup, dialplan execution, or your SDK.

The ACL is scoped to the workspace. Entries you add apply to every trunk
and every dialplan in that workspace, not to a single number or a single
route.

## Entry shape and how an address is matched

An entry is an **address** plus a **mask**. The mask determines how much
of the address has to agree:

| Part    | What it does                                                                 |
| ------- | ---------------------------------------------------------------------------- |
| Address | The peer's signalling IP, or the base address of a range.                     |
| Mask    | How many leading bits of the address must match. A full-width mask pins the entry to exactly one host; a shorter mask widens it to a subnet. |

Matching is done on the **source address of the SIP signalling packet**,
which is the address your peer actually sends from. That is not
necessarily the address in the `Contact` header, the `From` domain, or
the DNS name you configured elsewhere — NAT, an outbound SBC, or a
carrier's media gateway can all change it. If a peer sends from more
than one address (an HA pair, an anycast edge, a carrier with several
media gateways), every one of those addresses needs to be covered.

Because the list is an allow set, a request is admitted as soon as it
matches any entry. Adding a second, overlapping entry does not make the
first one stricter — the widest entry that covers an address is the one
that decides the outcome. Prefer the narrowest mask that still covers
the peer, and split a wide range into separate host entries when you can
enumerate the hosts.

## How trunk peers bypass the ACL

Inbound INVITEs from an address that is already configured as a **trunk
peer** bypass the ACL. The trunk configuration is itself the
authorisation: TeleQuick knows the peer's signalling address because
you gave it, so it does not require a second, redundant allow-list
entry.

Two consequences are worth keeping in mind:

- **Do not duplicate your carrier's addresses in the ACL.** They are
  already admitted through the trunk. Duplicating them only widens the
  surface that the ACL itself grants.
- **Removing or editing a trunk changes admission.** If you delete a
  trunk, or change the peer address on it, traffic from the old address
  falls back to the ACL. If no entry covers it, it stops being admitted.
  That can look like a routing failure when it is actually an admission
  failure.

The ACL is therefore for everything *else*: your own infrastructure,
on-prem PBXs, and any peer that does not have a trunk of its own.

## Registration versus IP allow-listing

IP allow-listing and REGISTER-based authentication answer two different
questions, and they compose rather than replace one another:

| | IP allow-listing (the ACL) | Registration credentials |
| --- | --- | --- |
| Answers | "May this address talk to the registrar?" | "Which endpoint is this, and can it prove it?" |
| Keyed on | Source address of the signalling packet | Per-endpoint credentials presented in SIP |
| Works when | The peer has a stable, known address | The peer's address is dynamic (roaming softphones, NAT, DHCP) |

An endpoint with valid credentials still has to reach the registrar
before it can register, so an address that is not admitted cannot
authenticate its way in. Conversely, an address that the ACL admits is
not automatically an authorised endpoint — it still has to satisfy
whatever authentication the endpoint's configuration requires.

Use IP allow-listing where the peer's address is static and you control
it. Use registration where it is not. Do not widen a mask to accommodate
a roaming endpoint; register it instead.

## What a rejected call looks like

A call that the ACL does not admit is rejected at the signalling edge,
before a call exists. That shapes where the evidence is:

- **No `CallEvent` reaches your SDK.** There is nothing to hang up and
  no `CHANNEL_HANGUP_COMPLETE` to inspect.
- **No CDR row is written.** The call never got far enough to have a
  `call_sid`, so it will not appear in the call list or in
  `telephony_cdrs`.
- **The only record is at the SIP layer**, in the exchange between the
  peer and the registrar.

This is precisely the failure shape that SIP packet capture exists for:
the call fails before any `CallEvent` reaches the SDK, so you have to
look at the SIP exchange itself. Enable HEPv3 capture and inspect the
response the registrar returned to the peer — see
[Telemetry](/platform/telemetry#sip-capture-hepv3).

Before you reach for capture, check the two cheap explanations first:
the peer is sending from a different source address than the one you
allow-listed, or the peer used to be covered by a trunk that has since
been edited or removed.

## Managing entries

The SIP ACL screen is the supported place to read and change entries.
The contact centre and the voice AI console render the same screen body,
so the list, the entry form, and the semantics described above are
identical in both.

Treat changes as changes to a security boundary:

- Adding an entry widens what the registrar accepts. Add the narrowest
  mask that covers the peer.
- Removing an entry takes effect for traffic that arrives afterwards. A
  peer that was relying on that entry stops being admitted, and its
  calls fail in the shape described above — silently, from the SDK's
  point of view.
- Before removing an entry, confirm whether the peer is also a trunk
  peer. If it is, it keeps working through the trunk bypass; if it is
  not, it stops.

## Related

- [Telemetry](/platform/telemetry) — HEPv3 SIP capture for admission failures
- [Authentication](/concepts/authentication) — credentials for the control and data planes