Lumaktaw sa nilalaman
14 araw na libreng trial, walang card9 wika176 uri ng negosyo · 50 app
TL· USD
Subukan ang live demoSimulan ang free trial

Wala pang Filipino na bersyon ang page na ito, kaya naka-English muna.

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