DoctorX logoDoctorX Get an API key

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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

ScopeGrants
authorize:readRead connected shops, their authorization status and channel capabilities.
authorize:writeStart a shop connect, disconnect a shop, and trigger catalog/size-chart pulls.
templates:readRead listing templates and live channel taxonomy.
templates:writeCreate, update, duplicate and delete listing templates.
products:readRead products, variants, per-shop sync state and listing quality.
products:writeCreate and update products, variants, images and per-listing attributes.
products:publishPublish, cross-list, schedule and end listings on connected marketplaces.
orders:readRead orders, line items, returns and status counts.
orders:writeCancel orders, set tracking, trigger order sync and stamp exports.
webhooks:manageRegister, update and inspect webhook endpoints and deliveries.
ebay:readRead eBay business policies, inventory locations, supported marketplaces and listing metadata.
ebay:writeCreate, update and delete eBay business policies and inventory locations, and set a shop's marketplace.
etsy:readRead Etsy shipping profiles, return policies, processing profiles, shop sections, personalization templates and shipping carriers.
etsy:writeCreate, update and delete Etsy shipping profiles, return policies, processing profiles, shop sections and personalization templates, and choose which are default.
amazon:readRead an Amazon shop's marketplace selection, content templates, publish defaults and the workspace product-type whitelist.
amazon:writeSet an Amazon shop's marketplace, manage its content templates, and set its publish defaults.
finances:readRead payouts, the seller funds summary and marketplace ledger entries. Grant only to a partner that needs financial data.
inventory:readRead each Amazon shop's stock per SKU, as the marketplace connection reports it.
orders:piiRead 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.

FieldWith orders:piiWithout
buyer.nameDanny ClarkD•••• C••••
buyer.emaildanny@example.comd••••@example.com
buyer.phone(+1)706•••••23••••••••••23
buyer.handledclark99••••rk99
shippingAddress.line11234 Peachtree Street•••••••••••••••••reet
shippingAddress.line2Apt 5•pt 5
shippingAddress.zip30815•0815
notesthe note text••••••••
returns[].reasonTextthe 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.