Skip to content
BlockNext

API keys

API keys authenticate machines: the two things you can do with BlockNext without signing in are starting a workflow and calling nodes over MCP, and both are gated by an API key.

Keys belong to an organization and are managed on its API Keys page. The plaintext key is shown once, at creation; the platform stores only a SHA-256 hash of it, so a lost key is regenerated, never recovered.

Scopes

Section titled “Scopes”

A key carries one or more scopes from a closed vocabulary — there is no wildcard, and a key with the wrong scope is rejected before the request reaches anything:

Scope Unlocks
workflows:trigger POST /task-runner/trigger/{workflowId} on platform-api
mcp:invoke POST /{serverId}/mcp on mcp-api — see Using the MCP server

Send the key on every request as the X-API-Key header:

Terminal window
curl -X POST https://api.blocknext.ai/platform/task-runner/trigger/<workflowId> \
  -H "X-API-Key: bnx_..." \
  -H "Content-Type: application/json" \
  -d '{ "runtimePrompt": "Summarize today's updates" }'

The key identifies the organization, so no organization ID appears in the path.

Triggering a workflow

Section titled “Triggering a workflow”

The request body is optional in full, and every field of it overrides part of the workflow for that run only — the saved canvas is never modified:

{
  "runtimePrompt": "Summarize today's updates",
  "nodes": [
    {
      "id": "2",
      "nodeId": "slack_send_message",
      "runtimeInstruction": "Post it to #general",
      "credentials": { "slack_oauth2": "credential:organization:<uuid>" }
    }
  ]
}
  • runtimePrompt — a natural-language message for the run, readable by every node as $trigger.prompt.
  • nodes — per-node overrides, matched by the node’s id on the canvas: a runtimeInstruction for that node and the credential references it should use.

You don’t have to assemble this by hand: the flow editor’s API Trigger panel (the </> button in the canvas toolbar) prints a ready-made cURL and JavaScript example for the open flow, prefilled with its nodes and credential placeholders.

The endpoint returns as soon as the run is accepted — follow its progress in the run view, not in the response.

Credential scope matching

Section titled “Credential scope matching”

API keys are issued per organization, and a key resolves only that organization’s credentials. A reference belonging to any other owner is rejected before anything is decrypted — see the credentials overview.

Rotating and revoking

Section titled “Rotating and revoking”
  • Regenerate replaces the key’s hash and returns a new plaintext key; the old one stops working immediately.
  • Delete revokes the key.
  • Each key records when it was last used, so an unused key is safe to remove.

Treat keys like passwords: one key per integration, so revoking one never takes the others down with it.