Live keys
Keys start with sbk_live_. Orders they create count in your real books.
Developers
Stop sharing logins with whoever builds your site
Give your website a key that can only do what you allow, and revoke it in one click.
Create and use a key
-
Open the screen
Go to Settings, Integrations, then Developer API. You need the permission to manage integrations.
-
Create API key
Press + Create API key. Enter a label, tick the scopes this key needs, and choose Live or Test (sandbox).
-
Copy the key
The full key is shown once. Store it on your server. If you lose it, revoke it and create another.
-
Send it as a Bearer token
Add the header Authorization: Bearer followed by the key to every request. No cookies or sessions are used.
curl "https://app.simplebks.com/api/public/v1/stock?limit=5" \
-H "Authorization: Bearer sbk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"Scopes
A key can only call endpoints its scopes allow. A missing scope returns 403 INSUFFICIENT_SCOPE.
| Scope | Allows | Default |
|---|---|---|
catalogue:read | Products, product by SKU, categories | Yes |
stock:read | Stock levels | Yes |
orders:read | Read an order | Yes |
orders:write | Create orders and report payment, fulfilment or cancellation | Yes |
images:write | Set a product picture from a URL on your site | No, grant it on purpose |
Live, test and limits
Test keys
Keys start with sbk_test_. Orders are flagged TEST in Web Orders so they never affect your real numbers.
Rate limits
Each key may make 120 requests per minute. Each IP address may make 300 per minute before the key is checked.
Errors you will meet
Every error response has success: false and a message. Most carry a code.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY, INVALID_API_KEY | No key, a wrong key, or a revoked key |
| 402 | PLAN_UPGRADE_REQUIRED | The business is not on a plan that includes the Developer API |
| 403 | INSUFFICIENT_SCOPE | The key lacks a scope the endpoint needs |
| 409 | IDEMPOTENCY_IN_PROGRESS, IDEMPOTENCY_PAYLOAD_MISMATCH | The same Idempotency-Key is racing, or was reused with different data |
| 429 | RATE_LIMITED | Too many requests. Wait and retry. Standard RateLimit headers are sent. |
Security
What Simplebks stores and how you take it back.
- Keys are stored as hashes. Simplebks keeps a one-way hash, so it cannot show you a key again.
- Keep keys on your server. Never put one in browser code, a mobile app or a public repository.
- Revoke from the same screen. Press Revoke next to a key. It stops working at once.
- Downgrades lock the API. The plan is rechecked about once a minute, so a business that drops below the Professional plan gets 402.
- Activity is logged without payloads. The Integration activity panel shows request metadata only: never keys, headers or request bodies.
FAQ
Who can create an API key?
A team member with the permission to manage integrations, on the Professional and Enterprise plans.
I lost my key. Can you show it again?
No. The key is shown once and only a hash is stored. Revoke it and create a new one.
What is the difference between live and test keys?
Live keys book real sales. Test keys book orders flagged TEST so your real figures stay clean while you build.
Is there a rate limit?
Yes: 120 requests per minute per key, and 300 per minute per IP address before authentication. Exceeding either returns 429.
Can a key write stock?
No. There is no stock-write scope. Only the orders you send move stock.
Start free and create your first API key on the Professional plan.