Authentication and scopes
Create API keys, choose what each key may do, send it with every request and stay inside the rate limit.
Every request to /v1 needs an API key. Keys belong to one business, never expire on their own and can be revoked at any time.
Create a key
- Open Settings → Developer in the Portal. Only the owner can manage keys.
- Choose Create key, type a name that tells you where it is used, and pick the access for each resource.
- Copy the key now. Bakasir stores only a hash, so it cannot be shown again. If you lose it, revoke it and create a new one.
A business can hold up to 20 active keys. Use one key per integration so you can revoke one without breaking the others.
Send the key
Send the key as a bearer token:
curl https://api.bakasir.com/v1/me \
-H "Authorization: Bearer bak_your_key_here"The header X-API-Key: bak_your_key_here works too. Always call the API from your server. Never put a key in a web page or a mobile app.
Scopes
Each key has a level per resource: no access, read or write. Write includes read.
| Resource | Levels | Used by |
|---|---|---|
products | read, write | /v1/products |
categories | read, write | /v1/categories |
stock | read, write | /v1/stock, /v1/stores |
customers | read, write | /v1/customers |
sales | read | /v1/sales |
orders | read | /v1/orders |
A request outside the key's access fails with 403 and the code insufficient_scope.
Rate limit
Each key may make 120 requests per minute by default. Bakasir can raise the limit for your business. Every response carries these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left in the current minute |
X-RateLimit-Reset | Unix time when the counter resets |
When you pass the limit you get 429 with the code rate_limited and a Retry-After header in seconds. Wait that long, then continue.
Revoke a key
Choose Revoke next to the key in Settings → Developer and hold the button. The key stops working immediately and requests with it return 401 with the code revoked_api_key. Revoking stays available even if the plugin lapses.
When a key is refused
| Status | Code | Reason |
|---|---|---|
| 401 | invalid_api_key | The key is missing, malformed or unknown |
| 401 | revoked_api_key | The key was revoked |
| 403 | plugin_inactive | The Public API plugin is not active for the business |
| 403 | tenant_inactive | The business account is suspended |
| 403 | insufficient_scope | The key has no access to this resource or method |
| 429 | rate_limited | Too many requests |
Last updated on