​

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 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. Manage credentials under Voice → Extensions in the dashboard, or through the public API at /api/v1/sip-credentials (reference). List, get, create, update, and rotate are all parity between the two surfaces; create, update, rotate, and delete require an owner or admin role.

​

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: 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 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. Once the digest verifies, inbound routing fans out to every device the credential holds a registration on; that model is 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 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:
   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.

​

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:
   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 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 — the concept page for creation, caps, rotation, and revocation.
• SIP digest verification model — the verification layers and why the local cap check fails open.
• SIP credentials API reference — the full request and response contract, with per-language examples.
• Extensions and desk phones, Desk phones: zero-touch provisioning, Browser Softphone — the adjacent device surfaces.