مواد پر جائیں
14 دن کا مفت ٹرائل، کارڈ کی ضرورت نہیں9 زبانیں176 کاروباری اقسام · 50 ایپس
UR· USD
لائیو ڈیمو آزمائیںمفت آزمائش شروع کریں

یہ صفحہ ابھی اردو میں دستیاب نہیں، اس لیے انگریزی میں دکھایا جا رہا ہے۔

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.

  • about 7 min

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.

Either header works
GET /api/v1/customers HTTP/1.1
Host: your-workspace.zmle.com
Authorization: Bearer fx_live_xxxxxxxx

# or
X-Api-Key: fx_live_xxxxxxxx

Scopes

Scopes are <resource>:read and <resource>:write; write implies read; * means everything. Give a key only what the integration needs.

ScopeAllows
customers:read / customers:writeList and read customers / create customers and update their contact details (PATCH)
inquiries:read / inquiries:writeLeads; creating one sends the same notifications as the website form
quotations:read / quotations:writeQuotations with items / create DRAFT quotations
invoices:read / invoices:writeInvoices with items and payments / create DRAFT invoices
orders:read, products:read, payments:readShop orders, products with stock, invoice payments
stock:read / stock:writeStock levels and locations / stock adjustments
appointments:read, pos:readAppointments, till sales and refunds
tasks:read / tasks:write, attachments:writeTasks; uploading photos and PDFs
webhooks:readThe event catalogue and the delivery log
Hosted only: catalog:read, bookings:read, bookings:write, webhooks:writeCategories, services, booking slots, booking appointments, managing webhook endpoints

Authentication errors

SituationAnswer
No key401 {"error":{"code":"unauthenticated"}}
Unknown, revoked or expired key401 with code invalid_key
Key lacks the scope403 with code insufficient_scope and required, e.g. invoices:read
Too many requests429 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