> ## 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.

# SIP credentials: provision digest-verified device identities

> What a SIP credential is, how to provision one for a desk phone or a browser softphone, how the REGISTER digest handshake verifies it at the voice edge, and the limits and rotation lifecycle that govern it.

# SIP credentials: provision digest-verified device identities

A SIP credential is the identity one device — a desk phone, a desktop or
mobile SIP app, or a browser softphone — uses to register with Orbit and
place or receive calls. This guide is the entry point for the feature
family: what a credential is, the provision → configure → rotate flow,
how the digest handshake verifies each registration, and the limits that
bound it. Worked examples at the end cover a desk phone and a browser
softphone step by step.

## 1. What a SIP credential is

A SIP credential is a password-bearing registration identity. It lets a
SIP user agent prove who it is to the voice edge so it can hold a live
binding, ring on inbound calls, and dial out. It is a different kind of
secret from the two identities it is most often confused with:

* **An API key** authenticates your code against the REST API. It never
  registers a device and a device never uses it.
* **A SIP trunk** authenticates one PBX or carrier system to another,
  system to system. A SIP credential authenticates one user agent — one
  phone or softphone — to Orbit. If you are interconnecting a PBX, you
  want the [SIP trunks guide](/guides/sip-trunk-setup) instead.

Each credential has a **username** derived from your organization and a
label you pick (`01h8x2j4-front-desk` shape) and a **password** Orbit
generates. The username stays stable for the credential's whole life;
the password is shown exactly once at creation and replaced by rotation.
On top of the identity, a credential carries tenant-owned limits —
allowed source IPs, a User-Agent lock, an outbound country block list, a
daily spend cap, a concurrent-call cap — all of which you manage
yourself. The full lifecycle model is [SIP credential
lifecycle](/concepts/sip-credential-lifecycle).

Manage credentials under **Voice → Extensions** in the dashboard, or
through the public API at `/api/v1/sip-credentials`
([reference](/api-reference/sip-credentials)). List, get, create,
update, and rotate are all parity between the two surfaces; create,
update, rotate, and delete require an **owner** or **admin** role.

<Warning>
  The plaintext password appears exactly once, in the create (or rotate)
  response. Save it immediately — it is not recoverable afterwards. If it
  is lost, rotate the credential and configure the device with the new
  password.
</Warning>

## 2. Provisioning flow: create, configure, rotate

The flow is the same three steps for every device class:

1. **Create.** `POST /api/v1/sip-credentials` with a label (and any
   limits you want on day one). The response carries the username, the
   one-time plaintext password, and the connection details — the SIP
   server host, ports, digest realm, transport, and media policy.
2. **Hand it to the device.** Copy the connection details into the
   desk phone or softphone's SIP account settings. Within seconds the
   device REGISTERs, the credential's `last_register_at` flips from
   `null` to the current time, and its `registered` flag goes true.
3. **Rotate on a schedule or on suspicion.** `POST
   /api/v1/sip-credentials/:id/rotate` mints a new password and revokes
   the old one immediately. The username does not change, so the device
   only needs its password field updated — nothing else in its
   configuration moves.

Rotation is deliberately cheap, so use it: when a device is lost or an
employee leaves, rotate instead of deleting and recreating, and the
label, extension number, and limits survive.

The create response fields map onto the device's SIP account settings
like this:

| Device setting | Response field | Example |
| - | - | - |
| SIP server / proxy / domain | `sip_server` | `sip.orbit.devotel.io` |
| Port | `sip_port_tls` (5061) / `sip_port_tcp` (5060) | `5061` |
| Username / auth username | `username` | `01h8x2j4-front-desk` |
| Password | `password` | one-time value from create or rotate |
| Digest realm (when a client asks) | `sip_realm` | `orbit.devotel.io` |
| Transport | `sip_transport_recommended` | TLS |
| Media encryption | `sip_srtp` | Mandatory |

`sip_server` and `sip_realm` are legitimately different values: the
server is the network host the device sends packets to; the realm is the
identity domain the voice edge challenges digest authentication with.
Clients that have one combined "domain" field only need the server.

If you manage a fleet of physical handsets, skip the manual copy-paste
entirely: [desk-phone zero-touch provisioning](/guides/voice-desk-phone-provisioning)
registers the phone's MAC, and the handset pulls rendered config —
including its paired SIP credential — from the provisioning URL on first
boot.

## 3. Digest verification: how REGISTER is checked

A device never sends its password. SIP digest authentication is a
challenge–response exchange: the voice edge answers a bare REGISTER
with a `401` carrying a one-time nonce, and the device retries with a
`response` hash computed over the stored secret, the nonce, and the
request. The edge re-computes the hash and only accepts the binding if
it matches. A captured response cannot be replayed against a fresh
nonce, and a stolen username alone registers nothing.

Create and rotation store the long-lived half of the secret (the
`HA1` hash over `username:realm:password`) in two algorithm variants,
so the edge can answer both legacy MD5 challenges and SHA-256
challenges — older handsets typically do MD5, newer clients can upgrade
to SHA-256.

Watch these failure signals when a device refuses to register; each maps
to a distinct cause, and all are visible on the credential's dashboard
row and in the audit feed:

* **401 / 403 with no binding** — the digest does not verify. Usually a
  mistyped password or a password that was rotated while the old one is
  still configured on the device.
* **Realm mismatch** — the device answered the challenge against the
  wrong realm. Check that any separate realm/domain field on the device
  holds `sip_realm` exactly as returned.
* **Disabled or expired** — the credential itself is blocking the
  registration (`enabled: false`, or an `expiresAt` that has passed).
  Re-enable or clear the expiry before touching the device.
* **`ip_locked`** — the source address is outside the credential's
  `allowedIpCidrs` list. Add the network's CIDR or clear the list.
* **`ua_locked`** — the User-Agent lock on the credential does not match
  the client's User-Agent header. Relax the lock or match the client.
* **Unsupported algorithm** — the device insists on a digest algorithm
  no stored hash can answer. Update the client firmware to gain SHA-256
  support.

Why each gate exists and the exact verification math each layer
recomputes is laid out in [SIP digest verification
model](/concepts/sip-digest-verification-model). Once the digest
verifies, inbound routing fans out to every device the credential holds
a registration on; that model is [Inbound voice
routing](/concepts/inbound-voice-routing).

## 4. Operational limits: caps, cooldowns, and the rotation lifecycle

The limits below are all tenant-owned controls — you set and clear every
one of them on your own credentials.

* **Per-credential caps.** A **concurrent-call cap** (1–100 simultaneous
  outbound calls) and an optional **registration cap** on how many
  distinct endpoints may hold live bindings at once. Both are enforced
  per credential; leave them unset for no cap. A blocked outbound call
  returns an accurate SIP status (403 / 402), never a silent drop.
* **Create and rotate rate limits.** Creating a credential and rotating
  a password are each limited to **10 requests per hour per workspace**;
  force-unregister is limited to **30 per hour**. Size bulk fleet
  rollouts around those ceilings — the [desk-phone bulk
  import](/guides/voice-desk-phone-provisioning) CSV path has its own
  50-phones-per-hour window.
* **Expiry.** Set `expiresAt` for contractor or seasonal devices; the
  credential stops authenticating after the timestamp without a manual
  revoke.
* **Disable vs delete.** `PATCH` with `enabled: false` suspends the
  credential: registrations and inbound/outbound calls stop, but the
  row, its limits, and its audit history survive. `DELETE` soft-deletes
  it and revokes immediately; hard delete is deliberately not exposed so
  the audit trail survives.
* **Force-unregister.** `POST /:id/unregister` evicts live REGISTER
  bindings right now — for a stolen device or a binding stuck behind a
  NAT edge. The device re-registers on its next refresh (\~60 seconds)
  unless you also disabled the credential, so pair the two when the
  goal is a real disconnect.
* **Rotation lifecycle.** Rotation replaces only the password hashes.
  Every limit, the extension number, the username, and the label
  survive, so a scheduled rotation (or an emergency one on suspicion)
  never re-opens configuration drift. Devices registered on the old
  password fall off on their next keepalive cycle — typically under 60
  seconds — and re-register with the new password once configured.

Every create, update, rotation, unregister, and delete lands in the
audit log with the username and label, so a credential fleet stays
observable across its lifecycle.

## 5. Worked example: desk-phone provisioning

Provision a Yealink on the front desk, locked to the office network.

1. Create the credential with extension, forward target, and an IP
   allow-list:

   ```bash theme={null}
   curl -X POST "https://api.orbit.devotel.io/api/v1/sip-credentials" \
     -H "X-API-Key: dv_live_sk_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "label": "front-desk",
       "extensionNumber": "101",
       "allowedIpCidrs": ["203.0.113.0/24"],
       "concurrentCallCap": 2,
       "forwardNoAnswerToUsername": "01h8x2j4-support",
       "notes": "Lobby desk phone, Yealink T54W"
     }'
   ```

2. Save the `password` from the 201 response immediately — it never
   appears again.

3. On the phone's web UI under **Account → Register**: **User Name**
   and **Authenticate Name** = the `username`; **Password** = the saved
   password; **SIP Server Host** = `sip.orbit.devotel.io`;
   **Port** = `5061`; **Transport** = TLS.

4. Confirm. The account row shows **Registered** within seconds; the
   credential's `registered` flag and `last_register_at` confirm it from
   the platform side. A REGISTER from any address outside
   `203.0.113.0/24` is refused as `ip_locked`.

For a fleet rollout, pair each handset by MAC instead and let it pull
this configuration itself: [desk-phone zero-touch
provisioning](/guides/voice-desk-phone-provisioning).

## 6. Worked example: browser softphone provisioning

Put a colleague on a softphone in their browser — the dashboard's
built-in phone or a third-party WebRTC client that REGISTERs over SIP.

1. Create the credential, naming the person and giving the device a
   reachability extension:

   ```bash theme={null}
   curl -X POST "https://api.orbit.devotel.io/api/v1/sip-credentials" \
     -H "X-API-Key: dv_live_sk_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "label": "maria-softphone",
       "extensionNumber": "205",
       "allowedUserAgent": "Bria"
     }'
   ```

2. Save the one-time `password`, then open the softphone's SIP account
   settings: **Username** = the `username` value, **Password** = the
   saved password, **Domain** = `sip.orbit.devotel.io`, **Port** =
   `5061`, **Transport** = TLS, **Media** = SRTP (mandatory).

3. The account flips to **Registered** in seconds. Colleagues reach it
   at extension `205`; inbound DID calls fork onto it alongside any desk
   phone paired to the same credential. The User-Agent lock means a
   leaked password cannot be used from a different SIP client.

If you want an in-dashboard calling surface with no SIP client at all,
the [Browser Softphone](/guides/voice-browser-softphone) rides the
signed-in dashboard session instead of a SIP REGISTER — pick that when
the operator already works in the dashboard.

## See also

* [SIP credential lifecycle](/concepts/sip-credential-lifecycle) — the
  concept page for creation, caps, rotation, and revocation.
* [SIP digest verification model](/concepts/sip-digest-verification-model)
  — the verification layers and why the local cap check fails open.
* [SIP credentials API reference](/api-reference/sip-credentials) — the
  full request and response contract, with per-language examples.
* [Extensions and desk phones](/guides/extensions-and-desk-phones),
  [Desk phones: zero-touch provisioning](/guides/voice-desk-phone-provisioning),
  [Browser Softphone](/guides/voice-browser-softphone) — the adjacent
  device surfaces.