এই পেজটি এখনো বাংলা ভাষায় পাওয়া যায় না, তাই ইংরেজিতে দেখানো হচ্ছে।
API keys and scopes
How keys are created and sent, which scopes exist, and what the API answers when a key is missing, wrong or too weak.
Every API key belongs to one workspace and only ever sees that workspace's data. Send it on every request as a bearer token or in the X-Api-Key header.
GET /api/v1/customers HTTP/1.1
Host: your-workspace.zmle.com
Authorization: Bearer fx_live_xxxxxxxx
# or
X-Api-Key: fx_live_xxxxxxxxScopes
Scopes are <resource>:read and <resource>:write; write implies read; * means everything. Give a key only what the integration needs.
| Scope | Allows |
|---|---|
customers:read / customers:write | List and read customers / create customers and update their contact details (PATCH) |
inquiries:read / inquiries:write | Leads; creating one sends the same notifications as the website form |
quotations:read / quotations:write | Quotations with items / create DRAFT quotations |
invoices:read / invoices:write | Invoices with items and payments / create DRAFT invoices |
orders:read, products:read, payments:read | Shop orders, products with stock, invoice payments |
stock:read / stock:write | Stock levels and locations / stock adjustments |
appointments:read, pos:read | Appointments, till sales and refunds |
tasks:read / tasks:write, attachments:write | Tasks; uploading photos and PDFs |
webhooks:read | The event catalogue and the delivery log |
Hosted only: catalog:read, bookings:read, bookings:write, webhooks:write | Categories, services, booking slots, booking appointments, managing webhook endpoints |
Authentication errors
| Situation | Answer |
|---|---|
| No key | 401 {"error":{"code":"unauthenticated"}} |
| Unknown, revoked or expired key | 401 with code invalid_key |
| Key lacks the scope | 403 with code insufficient_scope and required, e.g. invoices:read |
| Too many requests | 429 with code rate_limited, retryAfter and a Retry-After header |
Browser calls on the hosted platform are accepted only from the origins on the workspace's allow-list (Admin → Integrations & API → Connect your own website); other origins get
403 origin_not_allowed. Never put a key in browser code — call the API from your server.Marketplace integrations never ask the owner to create a key: at install the platform creates a dedicated key with exactly the scopes listed in
app.json (no *), sends it to your installUrl in a signed call, and revokes it on uninstall (course “Publish to the marketplace”).Written from: docs/API.md, src/lib/integrations/events.ts, src/app/api/v1/[[...path]]/route.ts, docs/DEVELOPERS/INTEGRATION-SPEC.md, src/lib/marketplace/install.ts