API Keys and the Developer Page

The REST API and Synapse's MCP server work on SynapseOrch Cloud as they do self-hosted, at https://api.synapseorch.com. What Cloud adds is who holds a key and what a key may reach. Both are under Settings → Developer.

The Developer page

• Start a workflow — two commands that work as they are once a key is in them: run a workflow, then check on it.
• Event stream — follow a run as it happens instead of polling its status.
• Create a key and Keys — the organisation's keys.

Right after you create a key, the page fills it into the commands so you can copy them as they are. Once you hide it (I've saved it — hide this), they read $SYNAPSE_API_KEY again.

curl -X POST https://api.synapseorch.com/api/v2/orchestrations/<orchestration-id>/run \
  -H "Authorization: Bearer $SYNAPSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Invoice 4021", "initial_state": {"customer_id": "12345"}}'

curl https://api.synapseorch.com/api/v2/orchestrations/runs/<run-id>/status \
  -H "Authorization: Bearer $SYNAPSE_API_KEY"

message arrives as the run's input, and initial_state seeds the run's state before its first step. The first answer carries the run_id the other calls take. The stream, GET /api/v2/orchestrations/runs/<run-id>/stream, closes after its done event; send the last id: you saw as Last-Event-ID to pick up where you dropped off. Every call is on Workflows API and Chat API.

Creating and revoking keys

• Owners and admins create and revoke keys. Every member can see the list: An admin can create keys for this organisation.
• Name a key after where it will be used. The key — sk-syn- and 32 hex characters — is shown once: Copy your key now. Only a hash is stored, so a lost key cannot be recovered; revoke it and create another.
• The list shows each key's name, its first characters and when it was last used, or never used.
• Revoke takes effect on the key's next request: Anything using it stops working immediately.

What a key can do

A key acts for the whole organisation, on the public API and over the MCP server. What it may do is fixed when it is made, and the list shows it on each key: run, or run and build.

Every key reads and runs. It can:

• read agents, workflows, schedules, runs and knowledge bases, and search them;
• start runs, follow them, list recent ones, answer a paused run and cancel one;
• chat with agents, approve or refuse the tool call a turn stopped on, and stop a turn;
• run a schedule now.

A key made with "Can also build" also changes the setup: it creates, changes and deletes agents, workflows, schedules, knowledge bases and their documents, and webhook endpoints. Over MCP that is the build and delete tools (a delete takes two calls, the second with the first's confirm_token). Tick it under Create a key only for a script that manages the workspace.

A key without it is refused anything that changes the setup, with 403: This API key was not given 'build'. A key that changes the workspace's setup is made in Settings → Developer with "Can also build". Over MCP it is not offered the build tools at all. A key's reach can't be widened later: make a new one. Keys made before 23 October 2026 run only, so a script that edits workflows needs a new key made to build.

No key can read members, billing, provider keys or other keys. Keep a build key as safe as a builder's own sign-in, and revoke one you no longer use.

A key works only at /api/v1, /api/v2 and the MCP server; the app refuses one — API keys work only at /api/v1 and /api/v2. — and the API never accepts the app's sign-in.

Limits

A key and the organisation each have a limit per minute, starting work has its own, and a key holds a bounded number of open streams — see Rate limits. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the limit closest to running out. A run also needs credits. Beyond your plan's runs at once it waits in line rather than failing: it reads queued, with its queue_position, until a slot frees.

Where Cloud's API differs

The same paths answer on both products. On Cloud:

• A chat's session_id is always made by the server: start without one, then pass back the one you get.
• A chat request with images is refused with 422.
• Event ids are strings — send back exactly the one you received. The v2 chat stream also takes ?after=<id> to resume.
• A webhook_url on a v2 run, resume or chat must be a public https address; a plain http one, or one that resolves to a private or internal address, is refused with 422. Deliveries are signed with your webhook_secret, as self-hosted.
• /api/v2/workers, /api/v2/queue/stats and /metrics are self-hosted only.

OpenAPI

Each version has its own document, readable without a key: https://api.synapseorch.com/api/v1/openapi.json and https://api.synapseorch.com/api/v2/openapi.json. Both list the Cloud and self-hosted servers. The docs' API reference is made from them: a page per endpoint, starting at Start a run.