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

# Per-channel connection mode: BYO vs platform default for subaccounts

> Set, per channel, whether your subaccounts send on the platform's shared connection or on a connection you bring yourself (BYO) — one active BYO connection per channel, inherited by every subaccount.

# Per-channel connection mode: BYO vs platform default

When you resell Orbit to your own customers, each channel your subaccounts use — SMS, Voice, Email, WhatsApp — runs on one of two connections:

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

This guide covers **reseller mode**: the parent-org capability that lets a whitelabel parent decide, per channel, which of those two connections every one of its subaccounts uses.

**You will:**

1. [Turn on reseller mode](#1-turn-on-reseller-mode)
2. [Bring your own connection for a channel](#2-bring-your-own-connection-for-a-channel)
3. [Revert a channel to the platform default](#3-revert-a-channel-to-the-platform-default)
4. [Read the current state](#4-read-the-current-state)

## What reseller mode is

Reseller mode is a capability flag on the **parent organization**. A whitelabel parent — an org that runs customer-facing subaccounts under its own brand — turns it on once, then manages a per-channel registry of connections it owns. Those connections are what "BYO" means here: your SIP trunk for voice termination, your SMPP account for SMS, your sending domain or SMTP relay for email, your own WhatsApp Business account or Meta app, your own LLM API keys, your own Stripe account for collections.

Subaccounts never configure any of this. They simply send, and the parent's active connection picks them up.

## The inheritance model

The model is deliberately simple — there is exactly one place to look, and one decision per channel:

* **One active BYO connection per channel.** The registry holds at most one connection per provider type. Activate your SIP trunk, and that trunk is the voice connection for the whole account family.
* **No per-subaccount registry.** There is no subaccount-level override. A subaccount cannot pick its own connection, and you cannot give one subaccount a different SIP trunk from another — BYO inheritance is all-or-nothing per channel, from the parent down.
* **Subaccounts inherit transparently.** When the parent has an active BYO connection for a channel, every subaccount's traffic on that channel rides it. When the parent has none — or reseller mode is off — every subaccount falls back to the platform default for that channel. A subaccount's own view of the connection settings says so, and who manages it.

Mixed mode is the normal case: bring your own SMPP account and SIP trunk, leave email on the platform default. Each channel is independent.

## Provider types

The registry accepts the following provider-type keys. Each maps to one channel lane:

| Provider type         | Channel it serves                                          |
| --------------------- | ---------------------------------------------------------- |
| `sip_trunk`           | Voice termination — outbound calls leave on your SIP trunk |
| `smpp`                | SMS termination — outbound SMS leaves on your SMPP account |
| `email_smtp`          | Transactional email — your sending domain / SMTP relay     |
| `whatsapp_waba`       | WhatsApp — your own WhatsApp Business account              |
| `whatsapp_meta_app`   | WhatsApp — your own Meta app                               |
| `llm_anthropic`       | AI features — your own Anthropic API key                   |
| `llm_openai`          | AI features — your own OpenAI API key                      |
| `voice_ai_elevenlabs` | AI voice — your own ElevenLabs account                     |
| `stripe_connect`      | Collections — your own Stripe account                      |

## 1. Turn on reseller mode

Reseller mode is the gate. Until it is on, no BYO connection resolves — everything runs on the platform default even if you've saved connections.

```bash theme={null}
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 }'
```

```json theme={null}
{
  "data": { "enabled": true },
  "meta": { "request_id": "req_abc123" }
}
```

Turning it **off** (`"enabled": false`) is a fail-safe, not a wipe: your saved connections stay on record, and every channel immediately falls back to the platform default. Turn it back on and the prior configuration picks up where it left off.

<Note>
  Only a **parent org** (an org with no parent of its own) can enable reseller mode. A subaccount calling this endpoint with `enabled: true` gets `403` — nested resellers are not a supported shape, and a subaccount can never flip itself into reseller mode.
</Note>

## 2. Bring your own connection for a channel

Define — or replace — a channel's connection with `PUT /organization/reseller/providers/:providerType`. Because the registry is one-connection-per-type, a `PUT` on an existing type overwrites the prior connection for that channel.

```bash theme={null}
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"
    }
  }'
```

Two things to know about the body:

* **`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. Send at most 50 fields, each value at most 2000 characters.

The response tells you where the channel resolves now:

```json theme={null}
{
  "data": {
    "provider_type": "smpp",
    "status": "active",
    "mode": "byo"
  },
  "meta": { "request_id": "req_def456" }
}
```

`mode: "byo"` means subaccounts' SMS now runs on your connection. If reseller mode is off, the same save returns `mode: "devotel_default"` — the connection is stored, just not in service.

## 3. Revert a channel to the platform default

Delete the registry entry and the channel flips back immediately:

```bash theme={null}
curl -X DELETE https://api.orbit.devotel.io/api/v1/organization/reseller/providers/smpp \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"
```

```json theme={null}
{
  "data": { "provider_type": "smpp", "deleted": true },
  "meta": { "request_id": "req_ghi789" }
}
```

Deleting a provider type that was never set is a safe no-op — the channel was already on the platform default.

## 4. Read the current state

One call returns the whole reseller slice:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/organization/reseller \
  -H "X-API-Key: dv_live_sk_YOUR_KEY"
```

```json theme={null}
{
  "data": {
    "enabled": true,
    "isSubaccount": false,
    "effectiveResellerOrgId": "org_parent_123",
    "providers": [
      {
        "providerType": "smpp",
        "status": "active",
        "feeMeterHook": null,
        "credentials": {
          "system_id": "••••••",
          "password": "••••••",
          "host": "••••••",
          "port": "••••••"
        }
      }
    ]
  },
  "meta": { "request_id": "req_jkl012" }
}
```

* **`enabled`** — the reseller-mode flag.
* **`isSubaccount`** — `true` when the caller itself is a subaccount. Subaccounts always receive an empty `providers` list; provider configuration is parent-only and never readable by a child org.
* **`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.

When you only need the resolution for one channel, ask for it directly: `GET /organization/reseller/resolve/:providerType` returns `{ "mode": "byo" | "devotel_default", "providerType", "config": … }`.

## Dashboard surface

Everything above is also a point-and-click surface — resellers typically have no admin-panel access, so the whole model is dashboard-driven. Open **Settings → Subaccounts** and use the **Channel Connection Mode** panel. It shows the master toggle (reseller mode on/off), one row per channel with its current mode — **Platform default**, **Your own connection (BYO)**, or a status badge such as **Pending — not in service** — and the buttons to activate a connection or revert a channel. Editing a saved field and re-saving rotates the credential.

The same panel appears in two places:

* The **Subaccounts list page** — manage the whole account family from one card.
* The **5-step new-subaccount wizard** — decide the connection mode at onboarding, in the same flow that sets plan, pricing, funding, and branding.

A subaccount viewing this panel sees a read-only note that its parent account manages the connection mode — it can never see or manage provider config.

## Per-channel behavior

Only two channels have named termination routes under this model today; the rest follow the same registry contract as their integrations land:

* **SMS** — when `smpp` is active on the parent's registry, subaccount SMS terminates on your SMPP account. Delete or deactivate it and SMS falls back to the platform default route.
* **Voice** — when `sip_trunk` is active, outbound calls from every subaccount terminate on your SIP trunk. Otherwise they run on the platform default.

The remaining provider types (email, WhatsApp, LLM keys, voice AI, Stripe) accept and persist registry entries through the same endpoints; each one takes effect per channel as its routing integration ships. Check the channel's changelog entry before relying on a non-voice/non-SMS type in production.

## Limits and rules

* **Exactly one active BYO connection per provider type.** A second `PUT` to the same type replaces the first — there is no multi-carrier mode.
* **Reseller mode is a capability gate.** Off means off: every channel resolves to the platform default regardless of saved connections.
* **No per-subaccount override.** Inheritance is all-or-nothing per channel from the parent. The only exception-free reading of "a subaccount wants its own connection" is: it wants its parent to bring one for the whole family.
* **Secrets are masked, never returned.** `GET` shows `••••••` per saved field. Loss of the plaintext is yours to handle — rotate by re-saving.
* **Parent-only management.** Provider config and the mode toggle reject subaccount callers with `403`.
* **Subaccount-created channels are unaffected.** A subaccount with no reseller-mode parent sees zero behavior change — everything it does resolves to the platform default, exactly as before.

## Related

* [Subaccounts API](/api-reference/subaccounts) — create, fund, price, and brand child orgs
* [Organization API](/api-reference/organization) — own-org profile, branding, and domains
* [SMS channel](/channels/sms) and [Voice channel](/channels/voice) — the two channels with live BYO termination today