> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Extensions and desk phones: SIP credentials and zero-touch provisioning

> Create SIP extensions for browser softphones, desktop apps, and physical desk phones; provision Polycom, Yealink, Cisco, and Grandstream handsets with zero-touch provisioning; roll them out in bulk by CSV; and confirm they come online.

# Extensions and desk phones

An **extension** is the SIP identity — a username, password, and optional
short extension number — that a person or device uses to place and receive
calls. A **desk phone** is the physical handset you attach to an extension
through zero-touch provisioning (ZTP). This guide covers both ends of the
onboard: create the extension, register the phone, and confirm it is live.

**Create and maintain extensions under Voice → Extensions; provision the
phones under Voice → Desk phones.** Both surfaces sit next to each other
on the Voice hub.

## SIP credential types

One extension powers several ways to answer it:

* **Browser softphone** — no install, no SIP details to enter. The
  extension opens the in-browser softphone from its detail page and
  connects on the owner's signed-in dashboard session. Ideal for hot-desks
  and shared workstations.
* **Softphone app** — a desktop or mobile app such as Zoiper, Linphone, or
  Bria, configured by scanning a QR code or by pasting the provisioning
  URI. The QR carries server, TLS port, transport, realm, SRTP, and codec
  fields, so nothing is typed.
* **Physical desk phone** — a Polycom, Yealink, Cisco, or Grandstream
  handset that pulls its config from a provisioning URL (zero-touch
  provisioning, below) or a downloaded vendor config file.
* **PBX** — an on-site PBX such as Asterisk or FreeSWITCH registers as a
  SIP trunk instead of an extension. Use the trunk surface for that:
  [Connect a SIP trunk](/guides/sip-trunk-setup). Extensions and trunks are
  separate channel types — pick the right one before wiring numbers.

## Create an extension

Open **Voice → Extensions** and click **Create extension**. The dialog and
the dedicated `/voice/extensions/new` page are the same form, so either
entry point works.

Fill in:

1. **Identity** — a label (required, up to 32 characters). The SIP username
   is derived from it — you never type one. Add an optional **extension
   number** (2–8 digits) so colleagues can dial it directly from
   **Voice → Colleagues**, plus optional free-text notes.
2. **Outbound** — outbound calling allowed or not, caller-ID pick
   (inherit the workspace default, choose one of the workspace's owned
   numbers, or fix a specific number), an optional daily spend cap, an
   optional concurrent-call cap, and an optional list of country codes to
   block. Leave a cap blank for unlimited; enter `0` to block outbound
   spend entirely.
3. **Security (optional)** — an expiry, allowed source-IP ranges (CIDR
   such as `10.0.0.0/24`), an allowed User-Agent match, and a forced codec
   if you do not want default auto-negotiation.
4. **Behavior (optional)** — do-not-disturb, per-leg recording flags,
   SIP username for forward-on-busy / forward-no-answer /
   forward-unavailable, and a voicemail PIN (4–8 digits, stored hashed).

**Save the one-time password.** Creation returns the plaintext password
exactly once — the dialog requires you to tick "I have saved the password"
before it can close. The extension's SIP username stays stable across
password rotations; if you lose it, **rotate** a new one from the detail
page instead of creating a second extension.

To hand the extension to a permanent desk phone, pair a **Desk phone**
device to it (next section) — the phone REGISTERs over that identity.
Mapping to an **agent** is optional: agents see the extension in
**Voice → Colleagues** as a click-to-call entry, and dispatch rules can
point to the extension's username.

## Zero-touch provisioning

Voice → Desk phones registers physical handsets in three steps:

1. **Register the phone.** Click **Register desk phone** and enter its
   MAC address from the label or the phone's **Status → Network** screen
   (colons, dashes, dots, or whitespace are accepted; the dialog
   normalizes them). Pick the vendor, optionally pair a SIP credential,
   and add a label and model (e.g. `Reception`, `VVX 450`).
2. **Copy the provisioning URL.** The registration returns a URL the
   phone's vendor redirect server needs on next boot. Paste it into
   **Polycom ZTP**, **Yealink RPS**, **Cisco EDOS**, or **Grandstream
   GDMS** — the dialog labels which one. The URL is also on the device's
   row afterwards.
3. **Factory-reset the phone.** On next boot it fetches its rendered
   config, authenticates to the SIP edge, and registers against the
   paired extension. The URL carries a signed token, so treat it like a
   password — anyone holding it can provision the phone as that extension.

Each new phone gets a 30-day claim window — register within that time or
the row flips to **Expired** in the table.

## Bulk CSV import

For fleets, skip the single dialog. In **Voice → Desk phones**, click
**Bulk import** and upload a CSV with a header row. Required columns are
`mac` and `vendor`; `label` and `model` are optional. Order- and
case-insensitive, and common header aliases are accepted (`mac address`,
`make`, `manufacturer`, `name`, `description`):

```csv theme={null}
mac,vendor,label,model
00:04:f2:aa:bb:cc,polycom,Reception,VVX 450
80:5e:c0:11:22:33,yealink,Desk 12,T46U
```

Each valid row registers one phone sequentially, and the result panel
reports registered / failed / skipped counts with per-line reasons — a
duplicate MAC or unknown vendor affects only that row, not the batch.
Fix the rejected lines and re-upload while the good rows stay registered.
The import permission is sized for fleets of this shape: up to 50 phones
per hour per workspace.

Two classes of row fail up front and are skipped before anything posts:

* **Invalid MAC** — the cell does not reduce to a 12-digit hex address.
* **Unknown vendor** — the value is not one of `polycom`, `yealink`,
  `cisco`, or `grandstream`.

Rows with a duplicate MAC or a server-side validation error land in the
**Failed** list in the result panel with the row's line number and reason.

## Live status and online indicator

After registration, the **Live status** card on the extension's detail
page (back under **Voice → Extensions → click the extension**) shows
whether a device is currently registered to this credential on the SIP
edge — with the UTC timestamp and source IP of the last REGISTER.
Statuses are **Registered**, **Not registered** (the binding expired),
or **Disabled** (the credential is administratively off). Most
softphones and phones re-REGISTER every 60–300 seconds, so brief gaps
self-heal; a persistent **Not registered** points at a network, NAT, or
stale-password issue. From the same card you can **Force unregister** to
evict a binding, or **Rotate password** for a lost or compromised
plaintext.

## Troubleshoot provisioning loops

Symptoms and checks, in the order to run them:

* **Phone never boots the config.** Factory-reset it again and confirm
  the redirect server (Polycom ZTP / Yealink RPS / Cisco EDOS /
  Grandstream GDMS) carries the exact provisioning URL you copied. The
  URL token is bound to one MAC — registering the wrong MAC on the
  redirect server leaves the phone in a loop.
* **Config fetched, registration loops.** The provisioning worked; the
  phone now loops REGISTER attempts. Check the extension's **Live
  status** card — if it flips `Registered` → `Not registered`, the
  re-register timer is failing. Confirm the password hasn't rotated, and
  that the phone can reach the SIP edge over TLS from its network.
* **NAT and SIP-ALG.** Corporate firewalls with SIP Application Layer
  Gateway rewrite SIP headers and break the binding. Disable SIP-ALG on
  the network router, or route over the TLS port Orbit provisions (the
  generated configs already prefer TLS) and allow the SIP edge outbound.
  If you set an allowed-source-IP list on the extension, the phone's
  egress IP must match it — an unmatched REGISTER is rejected before
  authentication.
* **Re-provision cleanly.** Rotate the extension's password at **Voice →
  Extensions**, delete the device at **Voice → Desk phones**, re-register
  the phone against the new URL, and factory-reset it. A force unregister
  alone is temporary; a stale device row is not.

## More

* [Extensions: reference](/voice/extensions) — the full field set, API,
  and rotate/disable/delete lifecycle.
* [Colleagues: live presence and directory](/voice/colleagues) — who can
  dial the extension from the browser.
* [Hot-desking: shared-device sign-in](/voice/hot-desking) — the browser
  softphone path.
* [SIP trunk troubleshooting](/troubleshooting/sip-trunk) — when the
  trunk path is the wrong one.
* [Voice quickstart](/voice/quickstart) — numbers, routing, and test
  calls.