​

Per-channel connection mode: BYO vs platform default

• Platform default — Orbit’s shared connection. Standard usage billing; nothing to set up.
• Your own connection (BYO) — a connection you bring (your own SIP trunk, SMPP account, email domain, WhatsApp Business account, and so on). Traffic on it carries a flat per-transaction platform fee in place of the platform default rate.

​

The inheritance model

• One active BYO connection per channel. The registry holds at most one connection per provider type.
• No per-subaccount registry. BYO inheritance is all-or-nothing per channel, from the parent down — a subaccount cannot pick its own connection.
• Subaccounts inherit transparently. An active parent BYO row carries every subaccount’s traffic on that channel; no row (or reseller mode off) falls back to the platform default.

​

Provider types

​

1. Turn on reseller mode

curl -X PATCH https://api.orbit.devotel.io/api/v1/organization/reseller/mode \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

{ "data": { "enabled": true }, "meta": { "request_id": "req_abc123" } }

​

2. Bring your own connection for a channel

curl -X PUT https://api.orbit.devotel.io/api/v1/organization/reseller/providers/smpp \
  -H "X-API-Key: dv_live_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "credentials": {
      "system_id": "your-smpp-system-id",
      "password": "your-smpp-password",
      "host": "smpp.yourcarrier.example",
      "port": "2775"
    }
  }'

• status — set it to "active" to put the connection in service. Anything else (pending, degraded, failed) keeps the registry entry but resolves the channel to the platform default. Only active rows take traffic.
• credentials — a plaintext map of whatever fields that connection needs. The API encrypts every value before it persists and never echoes a raw secret back: reads return each saved field as the masked sentinel ••••••. To rotate a secret, send the new value in the same field; to clear a field, send it as an empty string. At most 50 fields, each value at most 2000 characters.

{ "data": { "provider_type": "smpp", "status": "active", "mode": "byo" } }

​

3. Revert a channel to the platform default

curl -X DELETE https://api.orbit.devotel.io/api/v1/organization/reseller/providers/smpp \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

{ "data": { "provider_type": "smpp", "deleted": true } }

​

4. Read the current state

curl https://api.orbit.devotel.io/api/v1/organization/reseller \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"

{
  "data": {
    "enabled": true,
    "isSubaccount": false,
    "effectiveResellerOrgId": "org_parent_123",
    "providers": [
      { "providerType": "smpp", "status": "active",
        "credentials": { "password": "••••••" } }
    ]
  }
}

• enabled — the reseller-mode flag.
• isSubaccount — true when the caller itself is a subaccount; subaccounts always receive an empty providers list.
• effectiveResellerOrgId — the org the caller resolves against: its parent when the caller is a subaccount, itself when it is the reseller org, otherwise null.
• providers — the registry with credential values masked.

​

Dashboard

​

The master toggle

​

Per-row states and actions

• No registry row — a neutral Platform default badge; one action: Use your own connection (saves status: "active").
• Saved but not active (pending / degraded / failed) — the badge reads Pending — not in service for pending, or the raw status word in an amber/red tint for degraded/failed. Same single action: Use your own connection.
• Active BYO — a green Your own connection (BYO) badge with two actions: Save connection (re-PUT with credential edits, staying active) and Revert to platform default (a confirmation dialog that names the channel and warns credentials are deleted, then DELETE).

​

Per-channel status

​

Failure recovery: a credential rotation runbook

1. Detect. Subaccount sends on one channel start failing. Read GET /organization/reseller/resolve/:providerType — if it still reports mode: "byo" but sends fail, the registry believes the row is active and the upstream is rejecting the credential.
2. Mark the row degraded. PUT the providerType with status: "degraded" (no credential fields). The channel falls back to the platform default at the next resolution; the row stays on file.
3. Fix the credential. PUT the providerType again with the corrected fields and status: "active". The resolution flips back to byo with the first save that lands.
4. Verify from the parent. Re-read the resolver endpoint and confirm a subaccount’s next send succeeds. The parent’s registry row is the single source of truth; subaccounts never see the fix.

​

Limits and rules

​

Troubleshooting

• 403 — “a subaccount cannot enable it on itself” — the caller is itself a subaccount; reseller mode is parent-scope only. Use the parent org’s API key.
• 403 — “Provider configuration belongs to the reseller parent” — same cause on provider writes: provider rows are parent-owned.
• Saved a row but resolve still reports devotel_default — either the row’s status is below active (pending/degraded/failed), or reseller mode is off. Check GET /organization/reseller for enabled and the row’s status.
• Lost the plaintext of a saved field — nothing in the API returns it; rotate by re-saving the field with the replacement value.
• Branded SMPP / branded SIP preconditions — DNS pointing at your carrier’s endpoint and a TLS certificate for the hostname are still yours to own before the parent flips the lane; the registry stores the parameters but the carrier-side TLS/DNS is your responsibility so a connection is not declared active against an endpoint that fails the handshake.
• A row shows failed or degraded — that status flips the resolution to the platform default. Fix the upstream credential and re-activate with a PUT carrying status: "active".

​

Related

• Subaccounts API — create, fund, price, and brand child orgs
• Organization API — own-org profile, branding, and domains
• SMS channel and Voice channel — the first two channels whose BYO termination lanes are landing