यह पेज अभी हिन्दी में उपलब्ध नहीं है, इसलिए इसे अंग्रेज़ी में दिखाया जा रहा है।
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