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

# Create a new SIP credential

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



## OpenAPI

````yaml /openapi.yaml post /api/v1/sip-credentials
openapi: 3.1.0
info:
  title: Devotel CPaaS API
  description: Orbit by Devotel — Communications Platform as a Service API
  version: 1.0.0
  contact:
    name: Devotel
    url: https://devotel.io
    email: support@devotel.io
  license:
    name: Proprietary
servers:
  - url: https://api.orbit.devotel.io
    description: Production
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Messages
    description: >-
      Send and manage messages across all channels (SMS, WhatsApp, RCS, Email,
      Viber, etc.)
  - name: Agents
    description: AI agent creation, configuration, and execution
  - name: Voice
    description: Voice calls, IVR, conferencing, and SIP trunking
  - name: Webhooks
    description: Webhook endpoint management and delivery logs
  - name: Numbers
    description: Phone number search, provisioning, and configuration
  - name: Contacts
    description: Contact management, segmentation, and lifecycle tracking
  - name: Campaigns
    description: Marketing campaign orchestration and analytics
  - name: Flows
    description: Automation flow builder and execution engine
  - name: Templates
    description: Message template management and approval workflows
  - name: Settings
    description: Organization, channel, and user preference settings
  - name: Verify
    description: OTP generation and verification across channels
  - name: Push
    description: Push notification delivery via FCM and APNs
  - name: Telegram
    description: >-
      Telegram bring-your-own-bot channel: connect a bot, verify a chat against
      the shared sandbox bot, and read unified channel state. Production sends
      go through the Messaging API.
  - name: USSD
    description: >-
      Menu-driven USSD for feature phones: define a menu tree, simulate session
      steps, and host the tenant-scoped aggregator callback.
  - name: Integrations
    description: Third-party service connections and OAuth management
  - name: Files
    description: >-
      Server-to-server media upload, listing, retrieval, and deletion
      (signed-URL backed)
  - name: Messaging Services
    description: >-
      Twilio MessagingService-parity containers bundling sender pool, opt-out
      list, inbound webhook, and sticky-sender/geomatch flags
  - name: Sender Pools
    description: >-
      Group sending numbers into pools with a selection strategy (sticky /
      round-robin / random) for outbound sends
  - name: Opt-Out Lists
    description: >-
      Per-list STOP / HELP / START keyword sets and auto-response copy (Twilio
      Advanced Opt-Out parity)
  - name: SMPP
    description: Tenant BYO-SMPP bind credentials and upstream termination carriers
  - name: Commerce
    description: >-
      Unified omnichannel conversational-commerce: cart/checkout state machine,
      cross-channel payment reconciliation, hosted pay-by-link, native WhatsApp
      checkout, and agentic-checkout payment mandates
  - name: Orby
    description: >-
      In-dashboard Orby operator assistant: streamed assistant turns,
      conversation threads, product knowledge-base search, and the tool-action
      approval gate. Available to signed-in operators only (dashboard session
      auth — API-key requests are rejected).
paths:
  /api/v1/sip-credentials:
    post:
      tags:
        - SIP Credentials
      summary: Create a new SIP credential
      description: >-
        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.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            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.
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - name: X-Test-Mode
          in: header
          required: false
          description: >-
            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.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              description: >-
                Credential settings. `label` is the only required field —
                everything else has a platform default. Bounds are validated by
                the endpoint and reported as a 422 naming the field.
              properties:
                label:
                  type: string
                  description: >-
                    Required. Device label, 1-32 characters. Lowercased and
                    slugified into the SIP username (`<org-prefix>-<label>`),
                    which stays stable across password rotations.
                extensionNumber:
                  type: string
                  description: >-
                    Internal extension, 2-8 characters of digits, `*` or `#`.
                    Unique per organization.
                outboundEnabled:
                  type: boolean
                  description: >-
                    Whether the device may place outbound calls. Defaults to
                    true.
                outboundCallerIdMode:
                  type: string
                  enum:
                    - fixed
                    - pick_from_owned
                    - inherit_org
                  description: >-
                    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`.
                defaultCallerIdE164:
                  type: string
                  description: >-
                    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.
                outboundDailySpendCapCents:
                  type: integer
                  description: >-
                    Daily outbound spend ceiling for this device, in cents
                    (0-100000). Omit for no cap.
                outboundBlockedCountries:
                  type: array
                  items:
                    type: string
                  description: >-
                    ISO 3166-1 alpha-2 country codes this device may not dial,
                    for example `RU` or `KP`. Up to 50 entries.
                concurrentCallCap:
                  type: integer
                  description: >-
                    Maximum simultaneous calls for this device (1-100). Omit for
                    no cap.
                expiresAt:
                  type: string
                  description: >-
                    ISO 8601 timestamp after which the credential stops
                    authenticating, for example `2027-01-31T00:00:00Z`. Useful
                    for contractor or seasonal devices.
                dnd:
                  type: boolean
                  description: >-
                    Create the device in do-not-disturb, so inbound calls skip
                    it. Defaults to false.
                forceCodec:
                  type: string
                  enum:
                    - PCMU
                    - PCMA
                    - OPUS
                    - G722
                    - AMR-WB
                  description: >-
                    Pin media to a single codec instead of negotiating. Leave
                    unset unless the handset misbehaves during negotiation.
                forceRecordInbound:
                  type: boolean
                  description: Always record inbound calls to this device.
                forceRecordOutbound:
                  type: boolean
                  description: Always record outbound calls from this device.
                forwardBusyToUsername:
                  type: string
                  description: >-
                    SIP username in the same organization that inbound calls
                    ring when this device is busy.
                forwardNoAnswerToUsername:
                  type: string
                  description: >-
                    SIP username in the same organization that inbound calls
                    ring when this device does not answer.
                forwardUnavailableToUsername:
                  type: string
                  description: >-
                    SIP username in the same organization that inbound calls
                    ring when this device is not registered.
                allowedIpCidrs:
                  type: array
                  items:
                    type: string
                  description: >-
                    Source IP allow-list in CIDR notation, up to 20 entries.
                    Omit to accept registrations from any address.
                allowedUserAgent:
                  type: string
                  description: >-
                    Lock the credential to one SIP User-Agent string, for
                    example `Bria 6`. Registrations from any other client are
                    refused.
                voicemailPin:
                  type: string
                  description: >-
                    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.
                notes:
                  type: string
                  description: >-
                    Free-text note kept with the credential, up to 1000
                    characters.
            example:
              label: front-desk
              extensionNumber: '101'
              outboundEnabled: true
              outboundCallerIdMode: fixed
              defaultCallerIdE164: '+14155550123'
              concurrentCallCap: 2
              allowedIpCidrs:
                - 203.0.113.0/24
              notes: Lobby desk phone, Yealink T54W
        description: >-
          Credential settings. `label` is the only required field — everything
          else has a platform default. Bounds are validated by the endpoint and
          reported as a 422 naming the field.
      responses:
        '201':
          description: >-
            The created credential with the plaintext password (shown once),
            connection details (sip_server, sip_realm, sip_port_tls,
            sip_port_tcp), and metadata inside the standard `{ data, meta }`
            envelope.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: >-
                  The created credential with the plaintext password (shown
                  once), connection details (sip_server, sip_realm,
                  sip_port_tls, sip_port_tcp), and metadata inside the standard
                  `{ data, meta }` envelope.
          headers:
            Idempotency-Replay:
              description: >-
                Set to `true` when the response is a cached replay of a prior
                request with the same `Idempotency-Key`. Absent (or `false`) on
                first-write responses.
              schema:
                type: string
        '400':
          $ref: '#/components/responses/StandardError'
        '401':
          $ref: '#/components/responses/StandardError'
        '403':
          $ref: '#/components/responses/StandardError'
        '404':
          $ref: '#/components/responses/StandardError'
        '422':
          $ref: '#/components/responses/StandardError'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/StandardError'
components:
  responses:
    StandardError:
      description: >-
        Standard error envelope. `error.code` is machine-readable; see the
        [error reference](https://docs.orbit.devotel.io/reference/error-codes)
        for the catalogue.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - status
                properties:
                  code:
                    type: string
                    description: Machine-readable error code (e.g. INVALID_PHONE_NUMBER)
                  message:
                    type: string
                    description: Human-readable error description
                  status:
                    type: integer
                    description: HTTP status code
                  details:
                    type: object
                    additionalProperties: true
                    description: Additional context about the error
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  docs_url:
                    type: string
                    format: uri
                    description: Link to relevant error documentation
    RateLimitedResponse:
      description: >-
        Rate limit exceeded. Wait `error.retry_after` seconds (or read the
        `Retry-After` header) before retrying. Returned when the request would
        exceed the bucket identified by `X-RateLimit-Bucket`.
      headers:
        X-RateLimit-Limit:
          description: Total request quota for the current window.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: >-
            Absolute unix-epoch-seconds timestamp at which the current window
            resets.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Bucket:
          description: >-
            Name of the rate-limit bucket the request was bound by (e.g.
            `auth-write`, `money`, `agent-invoke`, or `custom:<max>/<window>`).
            Stripe-style — lets clients see which named cap they hit.
          schema:
            type: string
        RateLimit-Limit:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror of
            `X-RateLimit-Limit`. Some SDKs read only this form.
          schema:
            type: integer
            minimum: 0
        RateLimit-Remaining:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror of
            `X-RateLimit-Remaining`.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror — delta
            seconds from now until the window resets (NOT epoch).
          schema:
            type: integer
            minimum: 0
        Retry-After:
          description: >-
            RFC 7231 §7.1.3 — number of seconds the client should wait before
            retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - status
                  - retry_after
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMITED
                    description: >-
                      Always `RATE_LIMITED` — the global request-limiter 429.
                      Distinct from `RATE_LIMIT_EXCEEDED`, the live
                      per-recipient/per-tenant/per-resource frequency-cap 429
                      (not retired).
                  message:
                    type: string
                  status:
                    type: integer
                    enum:
                      - 429
                  retry_after:
                    type: integer
                    minimum: 1
                    description: >-
                      Seconds to wait before retrying. Mirrors `Retry-After`
                      header.
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  docs_url:
                    type: string
                    format: uri
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Dashboard JWT token from Clerk
    ApiKey:
      type: apiKey
      name: X-API-Key
      in: header
      description: Server-to-server API key (dv_live_sk_*)

````