Skip to main content

SIP Credentials API

SIP Credentials endpoints exposed by the Devotel CPaaS API Base path: /api/v1/sip-credentials Endpoint count: 7

List SIP credentials

GET /api/v1/sip-credentials
Returns a cursor-paginated list of SIP credentials (softphone registrations) for the authenticated organization. Each credential grants a SIP user agent access to register, route inbound calls, and optionally make outbound calls. Excludes plaintext passwords. Developer, viewer, admin, and owner roles can read; only admin/owner can create/modify.
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Get a SIP credential

GET /api/v1/sip-credentials/{id}
Returns a single SIP credential by id, including all settings and metadata but excluding the plaintext password (already shown at creation). Use this to view the current state for configuration or troubleshooting. Developer, viewer, admin, and owner roles can read.
string
required
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Create a new SIP credential

POST /api/v1/sip-credentials
Issues a new SIP credential for a softphone or desk phone. Returns the plaintext password exactly once; save it immediately as it is not recoverable. The credential is identified by a user-friendly label and a generated username. Configure your SIP client with the username, password, realm, and edge host returned in the response. Admin or owner only.
string
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
string
Required. Device label, 1-32 characters. Lowercased and slugified into the SIP username (<org-prefix>-<label>), which stays stable across password rotations.
string
Internal extension, 2-8 characters of digits, * or #. Unique per organization.
boolean
Whether the device may place outbound calls. Defaults to true.
string (enum: fixed|pick_from_owned|inherit_org)
How the From: number is chosen on outbound calls: fixed always uses defaultCallerIdE164, pick_from_owned lets the device send any number you own, inherit_org uses the organization default. Defaults to fixed.
string
E.164 number presented as the caller ID, for example +14155550123. Must be a number your organization owns, otherwise the request is rejected with 403.
integer
Daily outbound spend ceiling for this device, in cents (0-100000). Omit for no cap.
string[]
ISO 3166-1 alpha-2 country codes this device may not dial, for example RU or KP. Up to 50 entries.
integer
Maximum simultaneous calls for this device (1-100). Omit for no cap.
string
ISO 8601 timestamp after which the credential stops authenticating, for example 2027-01-31T00:00:00Z. Useful for contractor or seasonal devices.
boolean
Create the device in do-not-disturb, so inbound calls skip it. Defaults to false.
string (enum: PCMU|PCMA|OPUS|G722|AMR-WB)
Pin media to a single codec instead of negotiating. Leave unset unless the handset misbehaves during negotiation.
boolean
Always record inbound calls to this device.
boolean
Always record outbound calls from this device.
string
SIP username in the same organization that inbound calls ring when this device is busy.
string
SIP username in the same organization that inbound calls ring when this device does not answer.
string
SIP username in the same organization that inbound calls ring when this device is not registered.
string[]
Source IP allow-list in CIDR notation, up to 20 entries. Omit to accept registrations from any address.
string
Lock the credential to one SIP User-Agent string, for example Bria 6. Registrations from any other client are refused.
string
4-8 digit passcode the handset must key in on the *97 voicemail dial-in. Stored hashed and never returned; the read endpoints only report whether one is set.
string
Free-text note kept with the credential, up to 1000 characters.

Rotate a SIP credential password

POST /api/v1/sip-credentials/{id}/rotate
Generates a new password for an existing SIP credential, invalidating the old one immediately. The username remains the same so the credential does not need to be reconfigured in the user agent — only the password field changes. Returns the new plaintext password exactly once. Admin or owner only.
string
required
string
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Force unregister a SIP credential

POST /api/v1/sip-credentials/{id}/unregister
Evicts active SIP REGISTER bindings for a credential, disconnecting any currently-registered user agents immediately. The next REGISTER from the device (default ~60s) will recreate the binding. To permanently disconnect, combine this with a PATCH to set enabled=false. Useful when a device is stolen/compromised or stuck due to NAT edge cases. Admin or owner only.
string
required
string
Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Update a SIP credential

PATCH /api/v1/sip-credentials/{id}
Modifies settings on an existing SIP credential — for example to enable/disable it, set call limits, configure call forwarding, or manage voicemail PIN. Username is immutable. Password is rotated separately via the /rotate endpoint. Send only the fields you wish to change; omitted fields are left untouched. Admin or owner only.
string
required
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
string
Device label, 1-32 characters. Renaming does not change the SIP username, so registered devices keep working.
boolean
Set false to refuse further registrations and inbound calls without deleting the credential; set true to re-enable it.
string | null
Internal extension, 2-8 characters of digits, * or #. Send null to remove the extension.
boolean
Whether the device may place outbound calls.
string (enum: fixed|pick_from_owned|inherit_org)
How the From: number is chosen on outbound calls: fixed, pick_from_owned or inherit_org.
string | null
E.164 caller ID, for example +14155550123. Must be a number your organization owns. Send null to clear it.
integer | null
Daily outbound spend ceiling in cents (0-100000). Send null to remove the cap.
array | null
ISO 3166-1 alpha-2 country codes this device may not dial. Send null to allow every destination your organization allows.
integer | null
Maximum simultaneous calls (1-100). Send null to remove the cap.
string | null
ISO 8601 timestamp after which the credential stops authenticating. Send null so it never expires.
boolean
Do-not-disturb. Inbound calls skip the device while this is true; the change applies to the next call, not just new registrations.
string | null
Pin media to one of PCMU, PCMA, OPUS, G722 or AMR-WB. Send null to negotiate normally.
boolean
Always record inbound calls to this device.
boolean
Always record outbound calls from this device.
string | null
SIP username in the same organization to ring when this device is busy. Send null to stop forwarding.
string | null
SIP username in the same organization to ring when this device does not answer. Send null to stop forwarding.
string | null
SIP username in the same organization to ring when this device is not registered. Send null to stop forwarding.
array | null
Source IP allow-list in CIDR notation, up to 20 entries. Send null to accept registrations from any address.
string | null
Lock the credential to one SIP User-Agent string. Send null to accept any client.
string | null
4-8 digit passcode for the *97 voicemail dial-in. Send a new value to rotate it, or null to remove it. Stored hashed and never returned.
string | null
Free-text note, up to 1000 characters. Send null to clear it.

Delete a SIP credential

DELETE /api/v1/sip-credentials/{id}
Soft-deletes a SIP credential, immediately disabling it and preventing any further SIP REGISTERs from the associated user agent. The credential is marked deleted but remains in the audit trail. Hard-delete is not exposed for security. Admin or owner only. Returns 204 No Content.
string
required
string (enum: true|false)
Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.
Response: 204 No Content