SIP credentials API

Issue SIP credentials so a third-party softphone (Linphone, Zoiper, Bria, MicroSIP) or a hardware desk phone (Yealink, Grandstream) can register with Orbit’s voice edge and place or receive calls on your numbers. This page manages individual devices. For trunk-to-trunk connectivity between your PBX and Orbit, use the SIP trunks resource on the Voice API instead. Base path: /api/v1/sip-credentials Authentication: API key (X-API-Key) or session JWT. Creating and modifying credentials requires an admin or owner key; reads also work with developer and viewer keys.

Method	Path	Purpose
`GET`	`/api/v1/sip-credentials/`	List credentials
`POST`	`/api/v1/sip-credentials/`	Issue a new credential
`GET`	`/api/v1/sip-credentials/{id}`	Get a credential
`PATCH`	`/api/v1/sip-credentials/{id}`	Update label / restrictions
`DELETE`	`/api/v1/sip-credentials/{id}`	Revoke (soft delete)
`POST`	`/api/v1/sip-credentials/{id}/rotate`	Rotate password
`POST`	`/api/v1/sip-credentials/{id}/unregister`	Force-unregister all sessions

Quickstart: create a credential

POST a label and get back everything the device needs — username, a one-time password, and the connection details:

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": "Reception desk - Yealink T46U",
    "extensionNumber": "100",
    "outboundEnabled": true
  }'

201 Created — the full credential with the plaintext password, returned exactly once:

{
  "data": {
    "id": "sipcred_3f8a1b2c",
    "organization_id": "org_01H8X2J4K8YQJ9Z7ABCD",
    "username": "01h8x2j4-reception-desk-yealink-t46u",
    "label": "Reception desk - Yealink T46U",
    "enabled": true,
    "extension_number": "100",
    "outbound_enabled": true,
    "outbound_caller_id_mode": "fixed",
    "default_caller_id_e164": null,
    "outbound_daily_spend_cap_cents": null,
    "outbound_blocked_countries": null,
    "concurrent_call_cap": null,
    "expires_at": null,
    "dnd": false,
    "force_codec": null,
    "force_record_inbound": false,
    "force_record_outbound": false,
    "forward_busy_to_username": null,
    "forward_no_answer_to_username": null,
    "forward_unavailable_to_username": null,
    "last_register_at": null,
    "last_register_ip": null,
    "allowed_user_agent": null,
    "allowed_ip_cidrs": null,
    "voicemail_pin_set": false,
    "notes": null,
    "created_at": "2026-08-25T09:30:00.000Z",
    "updated_at": "2026-08-25T09:30:00.000Z",
    "sip_server": "sip.orbit.devotel.io",
    "sip_port_tls": 5061,
    "sip_port_tcp": 5060,
    "sip_realm": "orbit.devotel.io",
    "sip_transport_recommended": "TLS",
    "sip_srtp": "Mandatory",
    "password": "kR7mT2xQ9pLwH4nB8cY3dJ5v",
    "password_visible_once_warning": "Save this password now — it is not recoverable. Rotate via POST /sip-credentials/:id/rotate to issue a new one."
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2026-08-25T09:30:00.000Z"
  }
}

Save password immediately — it appears only in this response and in rotate responses. Every later read omits it. If it is lost, call POST /{id}/rotate for a new one. The username is derived from your organization and the label, so it stays stable when you rotate the password — registered devices only need the password field updated.

Configure the softphone or desk phone

Map the response fields to the device’s SIP account settings. The labels differ per client; the values do not.

Setting on the device	Response field	Example value
SIP server / proxy / domain	`sip_server`	`sip.orbit.devotel.io`
Port	`sip_port_tls` (5061) or `sip_port_tcp` (5060)	`5061`
Username / auth username	`username`	`01h8x2j4-reception-desk-yealink-t46u`
Password	`password`	the one-time value from create or rotate
Realm / domain (if asked separately)	`sip_realm`	`orbit.devotel.io`
Transport	`sip_transport_recommended`	TLS (TCP/UDP as fallback)
Media encryption	`sip_srtp`	Mandatory

sip_server and sip_realm are deliberately different values. sip_server is the network host the device sends REGISTER packets to; sip_realm is the digest realm the voice edge challenges with. Devices that ask for only one “domain” field work either way — the realm is only needed when a client separates the two.

Linphone (desktop or mobile)

Open Settings → SIP accounts → Add account.
Username: the username value. Password: the saved one-time password.
Domain / Server: sip.orbit.devotel.io (no port suffix; set the port separately).
Transport: TLS, port 5061. If TLS fails on an old network, fall back to TCP on 5060.
Save. Within a few seconds the account shows Registered. last_register_at on the credential flips from null to the current time.

Zoiper

Choose Add account → SIP.
Account name / username: the username value; password: the saved password.
Domain: sip.orbit.devotel.io, port: 5061, transport: TLS.
Leave outbound proxy empty — the server field above is sufficient.
The status line turns green when the REGISTER is accepted.

Bria

Account → SIP account → New.
User ID: the username; Password: the saved password; Domain: sip.orbit.devotel.io.
Under Advanced → Transport, pick TLS with port 5061. Under Security, set media encryption to SRTP (mandatory — the edge refuses unencrypted media).
Register. If Bria reports a certificate warning, switch your device clock to automatic and retry.

Yealink T46U (and similar desk phones)

Browse to the phone’s web UI → Account → Register.
Register Status: Enabled. Label / Display Name: anything human-readable.
User Name + Authenticate Name: the username value. Password: the saved password.
SIP Server 1 · Host: sip.orbit.devotel.io, Port: 5061, Transport: TLS.
Press Confirm; the account row shows Registered within a few seconds.

Set extensionNumber and the optional forward targets when you create the credential if you want the device reachable by short extension and covered on busy/no-answer/offline:

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",
    "outboundCallerIdMode": "fixed",
    "defaultCallerIdE164": "+14155550123",
    "concurrentCallCap": 2,
    "allowedIpCidrs": ["203.0.113.0/24"],
    "forwardNoAnswerToUsername": "01h8x2j4-support",
    "notes": "Lobby desk phone, Yealink T54W"
  }'

List and read credentials

List returns a cursor-paginated page; read returns one credential. Neither ever includes password material.

curl https://api.orbit.devotel.io/api/v1/sip-credentials/ \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK:

{
  "data": [
    {
      "id": "sipcred_3f8a1b2c",
      "username": "01h8x2j4-reception-desk-yealink-t46u",
      "label": "Reception desk - Yealink T46U",
      "enabled": true,
      "extension_number": "100",
      "outbound_enabled": true,
      "last_register_at": "2026-08-25T10:15:22.000Z",
      "last_register_ip": "198.51.100.24",
      "sip_server": "sip.orbit.devotel.io",
      "sip_port_tls": 5061,
      "sip_port_tcp": 5060,
      "sip_realm": "orbit.devotel.io",
      "sip_transport_recommended": "TLS",
      "sip_srtp": "Mandatory"
    }
  ],
  "meta": {
    "request_id": "req_e5f6a7b8",
    "timestamp": "2026-08-25T10:20:00.000Z",
    "pagination": {
      "cursor": "eyJjIjoiMjAyNi0wOC0yNVQwOTowMDowMFoifQ",
      "has_more": true
    }
  }
}

Pass meta.pagination.cursor as the cursor query parameter until has_more is false. Default page size is 25; the maximum is 200. Get a single credential — including the connection details a fresh device needs:

curl https://api.orbit.devotel.io/api/v1/sip-credentials/sipcred_3f8a1b2c \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK: same object shape as a list row, in the single-object envelope:

{
  "data": {
    "id": "sipcred_3f8a1b2c",
    "username": "01h8x2j4-reception-desk-yealink-t46u",
    "label": "Reception desk - Yealink T46U",
    "enabled": true,
    "extension_number": "100",
    "outbound_enabled": true,
    "outbound_caller_id_mode": "fixed",
    "dnd": false,
    "last_register_at": "2026-08-25T10:15:22.000Z",
    "voicemail_pin_set": false,
    "sip_server": "sip.orbit.devotel.io",
    "sip_port_tls": 5061,
    "sip_port_tcp": 5060,
    "sip_realm": "orbit.devotel.io",
    "sip_transport_recommended": "TLS",
    "sip_srtp": "Mandatory"
  },
  "meta": {
    "request_id": "req_c9d0e1f2",
    "timestamp": "2026-08-25T10:21:00.000Z"
  }
}

Lifecycle recipes

Disable or re-label a credential (PATCH)

Send only the fields you want to change. Send null on a nullable field to clear it. dnd: true makes inbound calls skip the device without touching its registration.

curl -X PATCH https://api.orbit.devotel.io/api/v1/sip-credentials/sipcred_3f8a1b2c \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Front desk - main lobby",
    "dnd": false,
    "concurrentCallCap": 3,
    "allowedIpCidrs": null
  }'

200 OK — the updated credential:

{
  "data": {
    "id": "sipcred_3f8a1b2c",
    "username": "01h8x2j4-reception-desk-yealink-t46u",
    "label": "Front desk - main lobby",
    "enabled": true,
    "dnd": false,
    "concurrent_call_cap": 3,
    "allowed_ip_cidrs": null,
    "sip_server": "sip.orbit.devotel.io",
    "sip_realm": "orbit.devotel.io",
    "updated_at": "2026-08-25T10:40:00.000Z"
  },
  "meta": {
    "request_id": "req_4a5b6c7d",
    "timestamp": "2026-08-25T10:40:00.000Z"
  }
}

The username is immutable by design — relabeling never breaks registered devices.

Rotate the password (POST /rotate)

Replaces the password immediately; the old one stops authenticating. The username is unchanged, so only the password field needs updating on the device.

curl -X POST https://api.orbit.devotel.io/api/v1/sip-credentials/sipcred_3f8a1b2c/rotate \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK — the new password, shown once:

{
  "data": {
    "id": "sipcred_3f8a1b2c",
    "username": "01h8x2j4-reception-desk-yealink-t46u",
    "sip_server": "sip.orbit.devotel.io",
    "sip_port_tls": 5061,
    "sip_port_tcp": 5060,
    "sip_realm": "orbit.devotel.io",
    "sip_transport_recommended": "TLS",
    "sip_srtp": "Mandatory",
    "password": "qN2wK8rT5vBxM4pC7yD9gH3j",
    "password_visible_once_warning": "Save this password now — it is not recoverable."
  },
  "meta": {
    "request_id": "req_8e9f0a1b",
    "timestamp": "2026-08-25T10:45:00.000Z"
  }
}

Force unregister sessions (POST /unregister)

Evicts the device’s active REGISTER bindings. The device re-registers on its next refresh (about 60 seconds for most clients), so combine with enabled: false for a permanent disconnect:

curl -X POST https://api.orbit.devotel.io/api/v1/sip-credentials/sipcred_3f8a1b2c/unregister \
  -H "X-API-Key: dv_live_sk_your_key_here"

200 OK:

{
  "data": {
    "ok": true,
    "bindings_evicted": 2
  },
  "meta": {
    "request_id": "req_2c3d4e5f",
    "timestamp": "2026-08-25T10:50:00.000Z"
  }
}

Delete (DELETE)

Soft-deletes the credential — REGISTERs stop immediately and the audit trail is kept. Returns 204 No Content with no body. Call unregister first if the device is actively ringing a call you want dropped.

curl -X DELETE https://api.orbit.devotel.io/api/v1/sip-credentials/sipcred_3f8a1b2c \
  -H "X-API-Key: dv_live_sk_your_key_here" -i

HTTP/1.1 204 No Content

Try it from the SDKs

There is no dedicated sipCredentials resource in the SDKs yet — use the generic request helper, which carries the same auth, retries, and idempotency handling as the typed resources.

Node.js

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const created = await orbit.request<any>('POST', '/sip-credentials', {
  label: 'Reception desk - Yealink T46U',
  extensionNumber: '100',
  outboundEnabled: true,
});
console.log(created.data.username);   // 01h8x2j4-reception-desk-yealink-t46u
console.log(created.data.password);   // shown once — store it now

const rotated = await orbit.request<any>(
  'POST',
  `/sip-credentials/${created.data.id}/rotate`,
);
console.log(rotated.data.password);   // new one-time password

Python

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

created = client.request("POST", "/sip-credentials", json_body={
    "label": "Reception desk - Yealink T46U",
    "extensionNumber": "100",
    "outboundEnabled": True,
})
print(created["data"]["username"])
print(created["data"]["password"])  # shown once — store it now

rotated = client.request(
    "POST",
    f"/sip-credentials/{created['data']['id']}/rotate",
)
print(rotated["data"]["password"])  # new one-time password

Troubleshooting

REGISTER returns 407 (Proxy Authentication Required) or repeated 401s. The digest was computed against the wrong realm. Configure the device with sip_realm (orbit.devotel.io) where it asks for a realm or domain, and keep sip_server (sip.orbit.devotel.io) in the server/proxy field. The two values are different by design; mixing them up fails every REGISTER. If the client has no separate realm field, it already uses the right one from the challenge. REGISTER never arrives (timeout, no response). The device is trying the wrong host or transport. Use sip_server from the response — never orbit.devotel.io, which is the app ingress and answers no SIP. Try TLS/5061 first; fall back to TCP/5060. The password copy is lost. Read endpoints never return it. Call POST /{id}/rotate and copy the new password value from that response. A credential exists but inbound never rings, or last_register_at stays null. No device has successfully registered. Check the client’s status screen, then confirm NAT/firewall egress below. NAT and firewall egress. The device must reach the SIP edge outbound on UDP/TCP 5060 and TLS 5061, and the media path negotiates SRTP. Corporate firewalls that block non-80/443 egress drop REGISTER silently. Home routers with aggressive NAT timing sometimes hold a stale binding — a POST /{id}/unregister call clears the server-side binding and the next refresh re-registers cleanly. 422 VALIDATION_ERROR. The response names the offending field in error.details.issues. Common causes: extensionNumber outside 2–8 characters of digits/*/#, a defaultCallerIdE164 that is not E.164, or a country code that is not ISO alpha-2. 409 CONFLICT. Another credential already has this label or extension. Pick a different one, or update the existing credential instead. 403 FORBIDDEN on create or PATCH. defaultCallerIdE164 must be a number your organization owns. The check always applies unless outboundCallerIdMode is inherit_org. 409 or 429 on rotate. Create and rotate accept a small number of requests per hour per organization. Rotate instead of re-creating, and keep automated rotations behind a queue if you manage many devices.

API Reference

All Endpoints

SIP credentials API: register softphones and desk phones against Orbit

SIP credentials API

Quickstart: create a credential

Configure the softphone or desk phone

Linphone (desktop or mobile)

Zoiper

Bria

Yealink T46U (and similar desk phones)

List and read credentials

Lifecycle recipes

Disable or re-label a credential (PATCH)

Rotate the password (POST /rotate)

Force unregister sessions (POST /unregister)

Delete (DELETE)

Try it from the SDKs

Node.js

Python

Troubleshooting

See also

​SIP credentials API

​Quickstart: create a credential

​Configure the softphone or desk phone

​Linphone (desktop or mobile)

​Zoiper

​Bria

​Yealink T46U (and similar desk phones)

​List and read credentials

​Lifecycle recipes

​Disable or re-label a credential (PATCH)

​Rotate the password (POST /rotate)

​Force unregister sessions (POST /unregister)

​Delete (DELETE)

​Try it from the SDKs

​Node.js

​Python

​Troubleshooting

​See also

SIP credentials API

Quickstart: create a credential

Configure the softphone or desk phone

Linphone (desktop or mobile)

Zoiper

Bria

Yealink T46U (and similar desk phones)

List and read credentials

Lifecycle recipes

Disable or re-label a credential (PATCH)

Rotate the password (POST /rotate)

Force unregister sessions (POST /unregister)

Delete (DELETE)

Try it from the SDKs

Node.js

Python

Troubleshooting

See also