Skip to main content

The Circus API Key Credential

Your Circus nodes don't just receive a webhook — they call back into the platform constantly: Init registers the start, Agent and Log report steps, Complete and Terminate end the run. Every one of those callbacks has to be authenticated, and that's what the Circus API credential is for.

The credential​

All five Circus nodes share a single credential type, circusApi ("Circus API"), with two fields:

  • apiKey — a Circus Platform API Key (created by the operator in the Circus UI under API Keys);
  • apiUrl — the base URL of the Circus platform (e.g. https://staging.circus.sh).

You configure it once in n8n's credential manager and select it on your Circus nodes. Under the hood, every call the nodes make to the platform's machine API (/api/machine/*) carries the key as an Authorization: Bearer header — you don't wire that up per node; the nodes do it for you.

Confirming it works​

The credential has a built-in test: on save, n8n calls the platform's /api/machine/health endpoint with your key. A healthy 200 means the URL and key are good — a quick way to catch a typo in the URL or a revoked key before you try to run anything.

Where the key comes from​

The apiKey itself is an operator responsibility: they create it in Circus, where it's shown in full only once at creation, and hand it to you (or configure it, if you're wearing both hats). Keys expire after 30 days and can be revoked at any time — so if a run suddenly can't call back, a revoked or expired key is a prime suspect. See the operator's Creating & Revoking API Keys for that side of the story.

Assign it everywhere​

A practical reminder: assign the circusApi credential to every Circus node in your workflow — Init, Agent, Log, Complete, Terminate. A missing credential on any one of them is a common cause of a workflow that fails partway through, because that node can't reach the platform.