Desk Phone Provisioning

A desk phone cannot log in. It boots, asks the network where its configuration lives, fetches a file, and registers with whatever it finds there. Everything on this page exists to make that one fetch land on the right file.

There are two ways to get a fleet online. They differ only in when you tell the platform which extension belongs to which handset.

	Pre-seed	Discover then assign
You know the MAC addresses in advance	yes	no
Work per phone after unboxing	none	pick an extension, then re-provision
Phone registers on first boot	yes	no

Both use the same site URL, and you can mix them — a phone that arrives without a pre-seeded MAC simply shows up in the discovered list.

1. Create the site enrollment URL

In Telephony → Extensions → Add phones → Auto discover, pick the site and create a token. You get one URL for the whole branch:

https://<your-provisioning-host>/v1/voice/provision/e/<token>/

Note the trailing /. It is a directory, not a file — without it the phone asks for <host>/<mac>.cfg, outside its provisioning directory, and every fetch after the first returns 404.

The token is not a credential

This URL never returns SIP passwords. A guessed token yields an empty device row and a file that says only "fetch from here next". Real credentials are served only from a device's own directory, and only once an extension is assigned. You can print this URL on a wall.

Two optional limits are worth setting: a device cap for the site, which bounds junk rows if the token leaks, and an expiry. Revoking a token does not disturb phones already enrolled.

2. Point DHCP option 66 at it

On a 3BB router

Open http://192.168.1.1 (some models use 192.168.0.1) and sign in as administrator, then find the DHCP section — typically:

Network → LAN → DHCP Server → DHCP Settings

Menu names vary by hardware. Look for any of: DHCP Option, Option 66, TFTP Server Name, Boot Server, Provisioning Server, or Vendor Specific DHCP Option.

Field	Value
Option	66
Type	String / Text
Value	the site URL from step 1
Scope	the LAN DHCP scope the phones sit in

No quotation marks, and keep the trailing /. Save, then restart the DHCP server or reboot the router once.

Many 3BB routers accept only a TFTP host

Firmware supplied by the ISP is often locked down, and some builds accept option 66 only as a bare hostname or IP — a full https:// URL is silently rejected or truncated. If the phone's Server URL is empty or wrong after a reboot, this is the most likely cause. Use one of the fallbacks below rather than fighting the firmware.

When the router has no option 66

1. Use your own router. Put the 3BB unit in bridge mode and run DHCP yourself.
2. Run a separate DHCP server — MikroTik, OpenWrt, pfSense, Windows DHCP, dnsmasq, or a UniFi gateway. For dnsmasq:

   dhcp-option=66,https://<your-provisioning-host>/v1/voice/provision/e/<token>/

3. Set it on the phone. On a Yealink: Settings → Auto Provision → Server URL. This works, but it is one visit per handset — the thing option 66 exists to avoid.

3. Choose how extensions get assigned

Pre-seed (zero-touch)

In Add phones → Import from CSV, upload a file with the MAC printed on each box:

name,extension,mac,vendor,model
Reception,1001,00:15:65:AA:BB:CC,yealink,yealink-t31w
Sales 1,1002,00:15:65:AA:BB:CD,yealink,yealink-t31w
Conference,1003,,poly,poly-vvx350

• name, vendor, model are required; extension must be an existing extension number.
• mac is optional per row — the third line above has none, so that phone falls back to discovery.
• Any separator style works (00:15:65:AA:BB:CC, 001565aabbcc, 00-15-65-aa-bb-cc, 0015.65aa.bbcc). The preview shows the form that will actually be stored.
• A MAC already registered to another device is rejected at upload rather than at boot.

Plug the phones in. Each one asks for its own <mac>.cfg, is recognised, and registers.

Discover then assign

Plug the phones in first. Each unknown handset creates a row in the discovered list within a few minutes, showing its MAC and a short activation code.

Then either pick an extension for each row and press Assign, or use Activate by code to claim one phone by the code beside it.

Assigning does not reach the phone by itself

The handset applies its new extension on its next auto-provision check, which can be many hours away. Reboot it, or press Autoprovision Now on the phone, to apply it immediately.

4. Confirm it worked

On the phone, Status shows its MAC and IP; Settings → Auto Provision shows the Server URL it received from DHCP. After provisioning, Account → Register Status should read Registered, and Status → System Log carries the fetch attempts.

In the dashboard, Telephony → Extensions → Activity logs every provisioning fetch and every registration lookup, including the failures — a config served with no extension bound, a MAC refused because it belongs to another organization, or a registration for an extension no device owns.

A phone showing localhost is pointing at itself

If the Server URL on the handset reads http://localhost:3003 or 127.0.0.1, the phone is resolving that to its own address and will never reach the platform. The provisioning host must be a name the phone can resolve on its own network.

Reference

Site enrollment tokens are managed through the organization-scoped API. Paths are relative to the API base shown in the API Reference; organizationId is the same value sent as X-TenantID.

Method	Path
GET	/organization/{organizationId}/voice/enrollment-tokens
POST	/organization/{organizationId}/voice/enrollment-tokens
DELETE	/organization/{organizationId}/voice/enrollment-tokens/{uuid}

POST takes org_node_uuid and optionally label, max_devices (0 = unlimited), and expires_at.

The phone-facing route the option 66 URL points at is unauthenticated by design — a booting handset has no credentials to present — and is therefore not published as a callable operation here. It is rate-limited per client address, and it refuses a MAC that belongs to another organization with the same 404 an unknown token receives, so a scanner cannot tell the two apart.