Dashboard

Authentication and scopes

View as Markdown

Every request carries an API key, except the few public endpoints. A key can do only what its scopes allow.

API keys

Send your API key in the x-api-key header. Create keys in your 3DAPI dashboard. Endpoints marked public need no key.

Scopes are read and write per resource:

  • products:read: read products, variants, designs and attachments.
  • products:write: create and change products, variants and designs.
  • orders:read: read orders and import issues.
  • orders:write: place and cancel orders.
  • orders:read_customer: see buyer personal data on orders.
  • stocks:read: read stocks and their batches.
  • stocks:write: create and change stocks, restock rules and purchases.
  • extras:read: read extras.
  • extras:write: create and change extras.
  • qc:read: read quality control tickets.
  • qc:write: answer and open quality control tickets.
  • wallet:read: read the wallet and transactions.
  • webhooks:read: read webhook endpoints, events and deliveries.
  • quotes:read: read quotes and approval requests (integrators).
  • quotes:write: create quotes and approval requests (integrators).

orders:read_customer adds buyer personal data (customer, full shipping address, notes) to orders and to order events; without it those fields are null and the address keeps only the country. Keys created before per-resource scopes carry a legacy permission: full has every scope above, order has orders:read and orders:write, pricing has none in this API. GET /v2/me returns both the stored scopes and the expanded effective_scopes.

Each operation lists the API key scopes it accepts in x-required-scopes: any one of them is enough, and a key with full access has them all. An empty list means no scope is needed (public operations, and operations every valid key may call). Signed-in dashboard sessions are not scoped.

Some operations are for one kind of account only, which each description says: designers (sellers on 3DAPI) or integrators (companies building on the API, see the Quotes and Integrator onboarding sections). x-audience on each operation lists the kinds of account it is for: designer, integrator, or both. Integrator accounts and their keys belong to this API only: the previous API (paths under /v1) refuses them by design, apart from /v1/me. Use the /v2 operations for quotes, orders and everything else.

HTTP
GET /v2/me
x-api-key: <your API key>

Create and revoke keys on the API keys page. Never put a key in browser or mobile code.

Scopes

The scopes stored on the API key, as chosen when it was created: per-resource scopes such as products:read, or a legacy permission (full, order or pricing). For a connected app, the scopes the user approved. See effective_scopes for what they allow. Null for sessions, which are not scoped.

pricingorderfullproducts:readproducts:writeorders:readorders:writeorders:read_customerstocks:readstocks:writeextras:readextras:writeqc:readqc:writewallet:readwebhooks:readquotes:readquotes:write

A request outside the key's scopes is refused with 403 and the code missing_scope. Expanded objects follow the scopes too: see Expanding objects.

Dashboard sessions

Session token of a signed-in API dashboard user. It is sent as Authorization: Bearer <token>. Sessions are not scoped. Server integrations should always use an API key.

Public endpoints

These endpoints answer without a key: