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

# Explore the API from the dashboard's Postman workbench

> The Postman page in the Orbit dashboard's Developer hub exports a collection and environment pre-wired to your organization — import them into Postman, paste one API key, and every request inherits your auth.

# Explore the API from the Postman workbench

The Developer hub ships a **Postman** page that exports a Postman collection and environment generated from the live API surface — one request per public endpoint, every JSON body seeded with a working example. Open it from **Developer → Postman Collection** in the dashboard.

This page covers where it lives, how import works, how auth is pre-wired, how to run sandbox and production side by side, and how to keep a local Postman workspace in sync. The import mechanics and first-response shapes are the same ones you'd use with the curated per-channel collections — the companion walkthrough: [Ship a sample request with the Postman collections](/guides/postman-collections-recipes). The difference here is that the dashboard export is generated per-organization over the whole catalog, not a static sample set.

## 1. Where it lives

In the dashboard sidebar, open **Developer → Postman Collection**. The page renders two download buttons:

* **Download Postman Collection** — one request per public endpoint, grouped into folders by tag (Messages, Numbers, Flows, Webhooks, Billing, and so on).
* **Download Postman Environment** — three variables pre-filled for your organization: `orbit_base_url`, `orbit_org_id`, and a blank `orbit_api_key` marked as a secret.

The downloads are served over your dashboard session, so the generated environment hits your organization rather than a shared template. Both buttons are plain GETs with a short timeout — click and either file is on disk in a second or two.

<Note>
  The seeded baseline — [`static/orbit-postman-collection.json`](/static/orbit-postman-collection.json) — is regenerated from the published OpenAPI spec whenever the docs are rebuilt, so following the same pattern offline means the collection you import matches the published contract, not a stale export.
</Note>

## 2. Import into Postman

From Postman's top bar: **Import → File**, pick the downloaded collection JSON, then repeat for the environment JSON. Postman registers the environment as **Orbit — \<your org name>** and the collection as **Orbit CPaaS — \<your org name>**.

If you prefer the command line — or need to pull the artifacts outside an active dashboard session — the same endpoints the buttons call respond to any signed `X-API-Key` request:

```bash theme={null}
curl -O "https://api.orbit.devotel.io/api/v1/developers/postman-collection" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

curl -O "https://api.orbit.devotel.io/api/v1/developers/postman-environment" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"
```

## 3. Auth is auto-injected at collection level

The exported collection carries one `auth.apikey` block pointing at the `X-API-Key` header with value `{{orbit_api_key}}`, and every request inside it is set to **Inherit auth from parent**. That means you paste your key ONCE — into the environment's `orbit_api_key` secret — and every request resolves the same header as a signed curl call:

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

The dashboard download DOESN'T embed a key — the environment arrives with `orbit_api_key` blank by design, so the file is safe to share with a teammate. After import, open the environment, paste a `dv_test_sk_…` or `dv_live_sk_…` key into `orbit_api_key`, and select the environment in Postman's picker. The variable is typed `secret`, so it stays in Postman's vault rather than syncing to the shared workspace.

<Warning>
  If one request ever returns 401 while the rest work, check its **Authorization** tab — a request individually switched off **Inherit auth from parent** drops the collection-level `X-API-Key`, which is the state behind most "worked yesterday, 401 today" confusion.
</Warning>

## 4. Sandbox and production, side by side

There is no separate sandbox host — `{{orbit_base_url}}` resolves to the same base; the environment gates sandbox via the key prefix, not the URL (full map: [Sandbox & base URLs](/guides/api-integration#base-urls)). Keep two environments in the picker so a wrong-environment send is a visible mistake:

1. **Orbit — Sandbox** — `orbit_api_key` set to `dv_test_sk_…`. Send calls simulate delivery (`test_sent`), so `to`/`from` don't have to be real numbers.
2. **Orbit — Live** — `orbit_api_key` set to `dv_live_sk_…`. The collection itself never changes — only the active environment does.

Saved requests live inside the collection, so every save you make (a renamed request, a tweaked body) persists across environment flips. Promotion before a live key touches real traffic: [Environments & promotion](/guides/api-integration#environments--promotion) and the [go-live checklist](/guides/go-live-checklist).

## 5. Keeping a local Postman app in sync

The exported JSON is a plain Collection v2.1 file, so import it once into your local Postman app (or a team workspace), then re-import in place whenever you've rotated a key or the API surface has changed. The dashboard page re-exports on every click — it never serves a cached artifact — so grabbing a fresh download is the whole sync loop.

If you share an exported collection with a teammate, re-import the same environment or one generated for THEIR organization — `orbit_org_id` is baked in per-organization, and a mixed org id on org-scoped endpoints produces 403s with no obvious cause. Rotated your key? Paste the new value into `orbit_api_key` before the old key's grace window expires (default 24 hours, up to 7 days) or requests start returning 401.

## 6. Three examples to fire first

Pick one request per class — a write, a read, a config create — against the Environment you just imported.

### send-message (write class)

`Messages → POST /messages/sms`:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: postman-first-send-1" \
  -d '{
    "from": "+16572262362",
    "to": "+14155552671",
    "body": "Hello from Postman."
  }'
```

Expect `202 Accepted` with `data.id` (`msg_…`) and `data.status` (`sent`, or `test_sent` in sandbox). Re-run the same request and the `Idempotency-Key` header protects you from a duplicate send.

### list-numbers (read class)

`Numbers → GET /numbers` — pass `?limit=10` to keep the first page small:

```bash theme={null}
curl -G "https://api.orbit.devotel.io/api/v1/numbers" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  --data-urlencode "limit=10"
```

Expect `200 OK` with an array under `data` and pagination controls under `meta` — the shape explains why list endpoints never return scalar counts. Details: [Numbers API](/api-reference/numbers).

### create-flow (config class)

`Flows → POST /flows`:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/flows \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Postman smoke flow",
    "trigger_type": "manual",
    "definition": { "nodes": [], "edges": [] }
  }'
```

Expect `201 Created` with `data.id` (`flow_…`) — that id is the handle for `POST /flows/:id/execute` and every version snapshot the builder writes. Shapes and trigger types: [Flows API](/api-reference/endpoints/flows).

## Troubleshooting

The failure classes here are the same ones the curated collections walk through, so branch on `error.code` and check the active environment's `orbit_api_key` first — never on message wording. Worked examples for the two shapes you hit first (401 from missing inherit-auth, 422 with a `details.field`): [Postman collections troubleshooting](/guides/postman-collections-recipes#5-troubleshooting).

## See also

* [Developer portal](/guides/developer-portal) — the org-generated collection and environment endpoints behind these buttons
* [Ship a sample request with the Postman collections](/guides/postman-collections-recipes) — the curated per-channel collections and import walkthrough
* [API integration](/guides/api-integration) — base URLs, authentication, channel map
* [API error handling by example](/guides/error-handling-examples) — typed errors past the two shapes above
* [Go-live checklist](/guides/go-live-checklist) — promotion gate before live traffic