Authentication
Every request carries an API key: http bearer (DoctorX API key (drx_live_...)).
Authentication
Send your API key as a bearer token on every request:
Authorization: Bearer drx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeys are created in the DoctorX dashboard under Settings -> Integrations -> API keys. The full key is shown once, at creation: only its hash is stored, so a lost key must be rotated rather than recovered. A key belongs to one tenant and may additionally be bound to specific shops, in which case every read and write is confined to those shops.
This is a server-to-server API. Never ship a key in a browser, a mobile app or any client you do not control.
Scopes
A key grants only what you select. A request without the required scope is rejected with
scope_insufficient and never partially applied.
| Scope | Grants |
|---|---|
authorize:read | Read connected shops, their authorization status and channel capabilities. |
authorize:write | Start a shop connect, disconnect a shop, and trigger catalog/size-chart pulls. |
templates:read | Read listing templates and live channel taxonomy. |
templates:write | Create, update, duplicate and delete listing templates. |
products:read | Read products, variants, per-shop sync state and listing quality. |
products:write | Create and update products, variants, images and per-listing attributes. |
products:publish | Publish, cross-list, schedule and end listings on connected marketplaces. |
orders:read | Read orders, line items, returns and status counts. |
orders:write | Cancel orders, set tracking, trigger order sync and stamp exports. |
webhooks:manage | Register, update and inspect webhook endpoints and deliveries. |
ebay:read | Read eBay business policies, inventory locations, supported marketplaces and listing metadata. |
ebay:write | Create, update and delete eBay business policies and inventory locations, and set a shop's marketplace. |
etsy:read | Read Etsy shipping profiles, return policies, processing profiles, shop sections, personalization templates and shipping carriers. |
etsy:write | Create, update and delete Etsy shipping profiles, return policies, processing profiles, shop sections and personalization templates, and choose which are default. |
amazon:read | Read an Amazon shop's marketplace selection, content templates, publish defaults and the workspace product-type whitelist. |
amazon:write | Set an Amazon shop's marketplace, manage its content templates, and set its publish defaults. |
finances:read | Read payouts, the seller funds summary and marketplace ledger entries. Grant only to a partner that needs financial data. |
inventory:read | Read each Amazon shop's stock per SKU, as the marketplace connection reports it. |
orders:pii | Read buyer personal data in full: name, email address, phone number, marketplace handle and street address. Without this scope those fields are returned MASKED and a search cannot match on them. Grant it only to a partner that ships parcels or answers buyers, and note that every read of it is recorded in the seller's PII access log. |
Buyer personal data
orders:pii is the one scope that unlocks FIELDS rather than an operation, so it needs
saying plainly. Every other scope answers "may this key call this endpoint"; this one answers
"may this key see who the buyer is".
Without it, orders:read still returns the whole order. What changes is these nine fields.
The examples are ILLUSTRATIVE: a mask keeps a short tail, and the number of dots follows the
length of the value it replaces.
| Field | With orders:pii | Without |
|---|---|---|
buyer.name | Danny Clark | D•••• C•••• |
buyer.email | danny@example.com | d••••@example.com |
buyer.phone | (+1)706•••••23 | ••••••••••23 |
buyer.handle | dclark99 | ••••rk99 |
shippingAddress.line1 | 1234 Peachtree Street | •••••••••••••••••reet |
shippingAddress.line2 | Apt 5 | •pt 5 |
shippingAddress.zip | 30815 | •0815 |
notes | the note text | •••••••• |
returns[].reasonText | the buyer's return reason | •••••••• |
Masking keeps a short tail so a value stays recognisable to a human reading a screen. Treat any masked value as opaque: never parse one, never compare one for equality, and never assume a length.
A channel may have masked the value before we ever saw it. TikTok Shop delivers buyer
names, phones and street addresses already partly redacted with *, so on those orders the
with-scope value is not a clean one either - it is whatever the marketplace sent. * is the
channel's masking, • is ours.
city, state and country are returned unchanged in both cases, deliberately. A
partner rating a shipment, choosing a carrier zone or reporting tax needs the destination, and
none of those three identifies a person at the granularity of a country's population.
zip IS masked, unlike its three neighbours, and the asymmetry is the point: a postcode
plus a city narrows to a street. That is also why no partial postcode is kept.
reasonCode is NOT masked while reasonText beside it is. The code is a channel enum
(BUYER_REMORSE, ITEM_DAMAGED) that names no person and is what a returns report groups
by; the text is the buyer writing about their own purchase.
GET /orders/export reports piiMasked in its result, beside capped, for the same
reason: a redacted CSV is indistinguishable from a complete one by status code, header row or
row count.
search narrows with the same switch. With the scope it matches on buyer name, email, phone,
handle and address as documented on the parameter. Without it those fields are excluded from
the match and everything else (order id, shop, tracking, notes, line items) still matches - a
search result is itself a disclosure, so a key that may not read a phone number must not be
able to confirm one by searching for it either.
Measured against one live tenant, same key, same 34 orders: a term found only in
buyer.email returned 0 rows without the scope and 34 with it; a term found only in
buyer.handle returned 0 and 1; and a fragment of channelOrderId returned 6 either way.
Search is narrowed, not switched off.
Two consequences worth planning for:
- A key issued before 2026-08-22 does not hold it. The scope is not granted retroactively: an existing key keeps every scope it had and reads masked buyer data until the seller adds this one. That is deliberate. Restoring a field is a one-click change the seller controls; un-sending a buyer's phone number to a partner is not possible at all.
- Every read of it is recorded. The seller sees, in their own workspace, which key read buyer data, when, from which address and which fields came back. The record holds field NAMES, never values, and is kept for twelve months.
