Guides
Authentication
On this page
API keys
Store owners (and staff with access to the Developers area) create keys in Settings → Developers → API keys. Each key has a name, a set of scopes and an optional expiry date. The full secret is shown once, when the key is created or rolled — SellOrchard only stores a hash of it.
The admin shows each key’s prefix and last four characters, when it was last used, and from which IP address.
Sending the key
Send the key in the Authorization header using the Bearer scheme. Keys in query strings are not accepted.
curl https://api.sellorchard.com/v1/products?limit=5 \
-H "Authorization: Bearer so_live_..."const res = await fetch("https://api.sellorchard.com/v1/products?limit=5", {
headers: { Authorization: `Bearer ${process.env.SELLORCHARD_API_KEY}` },
});
const { data, has_more, next_cursor } = await res.json();Scopes
Scopes limit what a key can do. A write_* scope includes the matching read_* scope. Give each integration only the scopes it needs; requests outside them fail with 403 and an error of type permission. Each endpoint in the reference lists the scopes it requires.
| Resource | Read | Write |
|---|---|---|
| Products, variants, categories & brands | read_products | write_products |
| Locations, inventory & purchase orders | read_inventory | write_inventory |
| Orders, fulfillments & refunds | read_orders | write_orders |
| Customers | read_customers | write_customers |
| Discount codes | read_discounts | write_discounts |
| Gift cards | read_gift_cards | write_gift_cards |
| Bookings | read_bookings | write_bookings |
| Reports | read_reports | — |
| Store details | read_store | — |
Live and test keys
Keys for stores on a paid plan start with so_live_. Stores on a free trial get so_test_ keys: they work against the real trial store with the same endpoints, but with lower rate limits. API access is included on the Pro and Advanced plans.
Rolling & revoking keys
- Roll issues a new secret for the same key (same name and scopes). The old secret stops working immediately, so deploy the new one straight away.
- Revoke permanently disables a key.
- Changes made with a key are recorded in the store’s activity log as “via API key <name>”.
Authentication errors
{
"error": {
"type": "authentication",
"message": "Invalid API key."
}
}