Getting started

Every call except the health check (GET /health) and the OpenAPI document (GET /openapi.json) needs an API key. Sandbox keys start with mk_test_ and work only on the sandbox, which holds synthetic data you are free to change.

• If you work for a distributor that uses Mikono, an administrator with the Manage settings permission creates the key in Settings → Developers → API keys, picks its scopes, and sends you the secret through a secure channel.
• If you are integrating a partner system, ask the Mikono team for a key on the sandbox organisation, Kampala Beverage Distributors (Demo).

The secret is shown once, when the key is created. Mikono stores only a hash of it, so nobody can show it to you again. If you lose it, the administrator rotates the key and you get a new secret. Keep it out of source control, URLs and logs.

Set the sandbox base URL and your key as shell variables. The sandbox base URL is:

export BASE="https://calculating-gnu-991.convex.site/api/v1"
export KEY="mk_test_your_key_here"

Then call GET /me. It needs no scope, so any valid key may call it, and it tells you which key, organisation and scopes the API sees.

curl -s "$BASE/me" \
  -H "Authorization: Bearer $KEY"

A successful call returns 200 with the key’s details:

{
  "name": "DMS bridge",
  "prefix": "mk_test_Ab12",
  "environment": "test",
  "organization": {
    "id": "wd709syv07f98c6w68x1eg6h058femh2",
    "name": "Kampala Beverage Distributors (Demo)"
  },
  "scopes": [
    "customers:read",
    "invoices:read"
  ],
  "rateLimits": {
    "read": {
      "perMinute": 600,
      "burst": 100
    },
    "write": {
      "perMinute": 120,
      "burst": 30
    },
    "ingest": {
      "perMinute": 60,
      "burst": 60
    }
  }
}

A 401 means the key is missing, mistyped, revoked, expired or meant for the other environment. A 403 api_disabled means the organisation has not turned API access on yet. The Errors guide lists every code.

GET /health needs no key. Use it for uptime checks. It returns the API version and the environment you reached.

curl -s "$BASE/health"

{
  "status": "ok",
  "version": "1.13.0",
  "environment": "test",
  "time": "2026-10-02T07:15:00.000Z"
}

Every call is recorded in the organisation’s API log, in Settings → Developers → API log. Each row shows the time, the key’s prefix, the method and path, the status, the duration, the request ID and the Idempotency-Key, and links to the record the call touched.

• Every response carries an X-Request-Id header. Quote it when you ask for help; it finds the row. You may send your own X-Request-Id (up to 64 letters, digits, _ or -) and Mikono echoes and logs it.
• For sandbox keys the log also keeps the request and response bodies, cut to 16 KB each, with personal fields removed. For production keys it never keeps bodies.
• The log never stores the key or the Authorization header.