Authentication

Every request, including /ping, requires X-Api-Key and X-Api-Secret. Send Accept: application/json, plus Content-Type: application/json for JSON bodies. The credential identifies the company; no tenant header or staff session is required.

Keep secrets on your server. Never include them in browser applications, URLs or repositories.

Scope	Operation
sales.orders:read	List sales.
sales.orders:write	Create draft sales at catalog prices.
sales.orders:assign-seller	Optionally assign a seller when creating a sale.

Scopes are assigned explicitly in Settings → API Keys. New scopes are not granted automatically. /ping needs authentication only.

Missing or invalid credentials return 401. Inactive keys, disallowed IPs, inactive companies or insufficient scopes return 403. Route scope checks include required_scope in the error response.

Identity and traceability

The authenticated credential identifies the creator as API · integration name. No fake human API user or seller configured on the key is required.

An optional header can identify the originating user in your external system:

X-External-Actor-Id: user-123

This is a reference declared by your integration, not an authenticated Simple user. It is audit metadata only: it never changes scopes, impersonates a staff member or assigns a seller. The maximum length is 255 characters; control characters are prohibited. Invalid values return 422. Avoid unnecessary personal data.

Creation responses include created_by with the actor type, ID, integration name, display label and optional external reference. Historical attribution is retained if the key is renamed or revoked.

A seller is a business assignment, separate from the creator. When creating sales, send seller_id in the JSON only if the key also has sales.orders:assign-seller. The seller must be an active member of the same company. Omitting it leaves the seller unassigned while preserving the API creator.