Environments and the sandbox

• A key works only in the environment that issued it, because the key’s hash is stored there. A sandbox key sent to production returns 401 wrong_environment, and so does the reverse.
• The production host is given to you when production access is turned on. Keep the base URL in your configuration, not in code, so moving from sandbox to production is a configuration change.
• GET /health reports which environment you reached in its environment field: test for the sandbox, live for production.

Sandbox keys belong to Kampala Beverage Distributors (Demo), a synthetic beverage distributor in Kampala. Every name, code, phone number and amount in it is made up. It holds:

• 60 outlets (bars, wholesalers, shops and restaurants) with DMS outlet codes of the form UG2xxxxxx, for example UG2104417, 15 on each route;
• 16 products with 6-digit DMS product codes, for example 780256 (Tusker Lager 500ml), priced per bottle in UGX, plus three returnable containers (two empty bottles and a crate) without DMS codes;
• four routes, each worked by one van salesman, and two trucks. Each route’s code, KBDVSM001 to KBDVSM004, is also its salesman’s DMS code: use it as salesmanCode on DMS documents;
• ten working days of trading history before the day it was seeded: trips, invoices, collections, customer returns, empties and stock movements, with every trip day settled; and that day’s trips still open.

• Partners ask the Mikono team for a sandbox key. The team creates it on the sandbox organisation and sends the secret through a secure channel. It can read every resource, post DMS documents (dms:ingest) and read their flags (dms:flags:read); it cannot write other records.
• The team can register a webhook endpoint for you at the same time, subscribed to dms.document.flagged and invoice.created. Its signing secret is also shown once.
• Anyone with the Manage settings permission on the sandbox organisation can also create keys with other scopes in Settings → Developers → API keys.

Sandbox keys start with mk_test_. Call GET /me with yours to see its scopes; the Getting started guide walks through the first call.

The sandbox organisation has one DMS connection, for Mikono’s own canonical JSON format (system canonical). Documents you post to it must carry these values:

A document with another distributor code is rejected with R07. One with a customer or product code the sandbox does not know is held with R08 and retried for 48 hours, then rejected with R08. The DMS integration guide lists every reason code.

The sandbox is not reset. Records you create through the API stay, alongside the synthetic history, and other partners testing on the sandbox can see them.

• Every write made with an API key is recorded in the organisation’s audit log with the source Integration, the key and the request ID, and is attributed to the key’s own service account, named API: <key name>.
• Documents posted to the DMS connection are attributed to the connection’s service account, DMS: canonical (KBD001), and are also audited with the source Integration.
• Settings → Developers → API log lists every call, with a link to the record it touched.

If the sandbox is not connected to a QuickBooks company, posted documents carry their Mikono reference and quickbooksRef: null.

• Sign in to Mikono with an account that is a member of Kampala Beverage Distributors (Demo), and select that organisation. Creating keys needs the Manage settings permission.
• Open Settings → Developers. If API access is off, turn it on there.
• Under API keys, choose Create key. Name it after the system that will use it, and pick only the scopes it needs, for example customers:read and invoices:read.
• Copy the secret. It starts with mk_test_ and is shown once; the list shows only its prefix after that.
• Call GET /me with the key to check its organisation and scopes.

• API access is off for every organisation until one of its administrators turns it on in Settings → Developers.
• Production keys never have request or response bodies kept in the API log.
• The same endpoints, rules and limits apply in both environments. A flow that works in the sandbox works in production with a production key and base URL.

Versioning is described in the Changelog.