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 accept an API key. (MCP clients with authorization support can also sign in through OAuth instead of using a 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 for provider servers — 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.