Authentication and scopes
Send the key in the Authorization header on every request:
Authorization: Bearer mtk_…A missing or unknown key gets 401 UNAUTHENTICATED. A revoked key stops working. An account whose subscription is suspended gets 403 SUSPENDED.
Scopes
Section titled “Scopes”A key does only what its scopes allow; the reference names the scope each operation needs. Write scopes include their read scope.
| Scope | Allows |
|---|---|
kb:read |
Listing knowledge bases and products. Every key has it. |
categories:read, categories:write |
Knowledge base categories. |
articles:read, articles:write |
Articles and their drafts. |
articles:publish |
Publishing and unpublishing articles. |
crm:read |
Contacts, clients, catalog, orders, subscriptions, custom fields and revenue. |
crm:write |
Creating, updating and syncing those records. |
crm:configure |
Stores and custom field definitions (account configuration). |
tickets:read |
Tickets, their messages and the customer card. |
tickets:write |
Replying, notes, assignment, status, priority, tags and merging. |
The admin offers presets: Read only, Content editor, Content publisher, Support agent and CRM sync (crm:read, crm:write, crm:configure).
Products
Section titled “Products”A key can be limited to some products. Calls addressed to any other product get 404 PRODUCT_NOT_FOUND, as if it did not exist. GET /v1/products lists the ones a key may use.
What a key writes
Section titled “What a key writes”Replies, notes and changes made with a key appear in Motenya under the key’s name, for example Zapier (API), and in the audit trail.
Rate limits
Section titled “Rate limits”Each key may make 300 requests a minute. Past that, requests get 429 RATE_LIMITED with a Retry-After header; wait that many seconds and retry. For bulk imports, use batches: one call carries up to 100 records.