Keys and scopes
A key says who is calling and what they may do. Each company makes its own keys in Settings, Developers.
Two kinds of key
| Kind | Looks like | Use it in | Limit |
|---|---|---|---|
| Publishable | xpk_live_ and 32 characters | Browser code. It can only do the safe things in the table below. | 120 calls a minute |
| Secret | xsk_live_ and 48 characters | Your server only. It can also read orders and customers and manage webhooks. | 600 calls a minute |
A key is shown once, when you make it. Xatern One keeps only a fingerprint of it. If you lose a key, stop it and make a new one.
Send the key
Use the Authorization header. The X-Api-Key header also works.
curl https://api.xatern.com/v1/me -H "Authorization: Bearer xsk_live_YOUR_SECRET_KEY"
curl https://api.xatern.com/v1/me -H "X-Api-Key: xsk_live_YOUR_SECRET_KEY"Scopes
A scope is one permission. When you make a key you tick the scopes it gets. A publishable key gets all four publishable scopes by default. A secret key gets every scope.
| Scope | What it allows | Publishable key |
|---|---|---|
catalog:read | Read the catalog | Yes |
orders:create | Place an order, upload a payment proof, and read the shopper view and waybill with the order token | Yes |
subscribers:create | Add an email to the mailing list | Yes |
leads:create | Send a website enquiry into the CRM | Yes |
orders:read | List orders and get any order without a token. Staff view, with no internal notes or file paths | No |
customers:read | List customers | No |
webhooks:manage | Make and manage webhook endpoints and read deliveries | No |
A call without the right scope returns 403 with the code missing_scope.
Browsers and origins
- Browser requests are allowed with publishable keys only.
- If your company has a website address in Xatern One, the request must come from that address over
https.localhostis always allowed so you can build. - A secret key used from a browser is refused with
browser_not_allowed.
Limits
Calls are counted per key, per minute. Over the limit you get 429 with the code rate_limited and a Retry-After: 60 header. Daily totals for each key show in Settings, Developers. See Errors and limits.
Stop a key
In Settings, Developers, choose Stop key. Calls with that key fail at once with invalid_key.
Legacy shop keys
A website key that starts with xshop_ still works on the API. It acts like a key with the scopes catalog:read, orders:create and subscribers:create, with the limit of a secret key. Use it from your server only. Legacy lead keys are not accepted. Make a new key when you can.
Xatern One API v1. Example data on these pages is made up.