API Reference
SIP Trunk

Get the workspace's SIP trunk

GET
/v1/sip-trunk

A workspace has at most one SIP trunk. Returns sip_trunk.not_found if none has been connected.

Authorization

bearerAuth
AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/sip-trunk"
{  "auth_mode": "registration",  "label": "string",  "realm": "string",  "proxy": "string",  "transport": "udp",  "auth_username": "string",  "has_password": true,  "signaling_ips": [    "string"  ],  "media_ips": [    "string"  ],  "country_code": "string",  "outbound_number_format": "string",  "outbound_codec_prefs": "string",  "outbound_media_security": "string",  "status": "pending",  "last_error": "string"}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254720000003"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254720000003"  }}

Revoke a SIP credential, or remove a revoked one DELETE

Two steps, same endpoint. On an **active** credential this revokes it. The account is deleted on the registrar first, which flushes any live registration, so the device stops working immediately rather than lasting until its current registration expires, and the row is kept, marked `revoked`, so it still appears in the list. Called again on that **revoked** row, it removes the row for good. The purge is deliberately gated on the row already being revoked. That is what guarantees the registrar account is gone: a one-step hard delete could leave an account still able to register that we no longer hold the handle to revoke. Revoking frees the credential's slot against the per-number cap and releases its internal extension for reuse. Caller must have writer access to the workspace.

Connect a SIP trunk to the workspace POST

Connects the workspace's trunk. A workspace has at most one, so there is no trunk ID in the path. Refuses with `sip_trunk.already_exists` when a trunk is already connected, rather than replacing it: swapping a live trunk would drop calls in flight, and on an `ip_allowlist` trunk would reset an approved connection back to `pending_approval`. Use `PUT` to change an existing trunk. The resulting `status` depends on `auth_mode`, and the difference is a security one. A `registration` trunk starts `pending` and needs **no operator approval**, the carrier authenticates with a username and password on every REGISTER, so it proves itself on every call. An `ip_allowlist` trunk starts `pending_approval` and never self-activates: trusting a signalling IP is a standing grant that only an operator can make.