Skip to content

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.

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).

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.

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.

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.