niiko/developers

Get started

Quickstart

Three steps: create a key, switch the action on, call.

Last updated

1 · Create an API key

In your workspace: Settings → Developers → Keys. Pick the scopes of the actions the integration will exercise. The key is shown once, when created — it starts with nk_.

2 · Switch the action on

Settings → Connections, column “API & MCP”. Each action has its own switch, off by default. Holding a key is not enough: the key and the switch are two decisions made by different people.

Two permissions, not one

Besides the credential, every action and every read needs the workspace owner to have switched it on (Settings → Connections, column “API & MCP”). The reason is deliberate: whoever holds a key and whoever owns the workspace are usually two different people, and each one gets to decide.

3 · Call

Every example on this site is generated from the same contract the server enforces. Pick your client:

# One request, one idempotency key: retrying with the same key never runs twice.
curl -X POST https://niiko.org/api/v1/actions/miira.lead_create \
  -H "Authorization: Bearer nk_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "submissionId": "01890a5d-ac96-774b-bcce-b302099a8057",
    "source": "web_form"
  }'
# 200 → done · 202 → pending_approval (a person signs later) · 4xx → refused, with a named reason

What to read next

  • Three outcomes — Done, refused with a named reason, or waiting for a signature.
  • Idempotency — With an Idempotency-Key nothing runs twice.
  • Webhooks — Register a destination and niiko notifies you when something resolves — above all what stayed pending_approval, which by definition finishes after you hung up.
  • All actions
  • All reads — they take an OAuth token instead of a key, granted by a person.