Connect and credentials

The Connect page (/connect) is the directory of every external service a recipe can talk to and every Neurocad credential a recipe can act on behalf of. Adding a connection here makes its credentials available to nodes in the canvas; removing it (or letting it drift to a bad state) is what causes "missing credential" or needs_reauth errors at deploy and run time.

This doc covers what credential types exist, how they're created and refreshed, and how they're used by recipe nodes.

What you'll find on /connect

The Connect directory shows one card per registered credential type, each with a status pill in the corner:

Not connected — Never been set up.
Connections — You have 1-2 live connections of this type. Live means active or needs_reauth — the second is broken but recoverable, so the card stays visible.
Reconnect required — There's a dormant connection in uninstalled / revoked / error and no live one.
Managed — The type is platform-provisioned. Your org gets a connection automatically; you don't add or remove it.
Not provisioned — Managed type that hasn't been provisioned for your org yet (talk to your operator).

Click a card to go to the per-type page (/connect/provider/[type]). From there:

Add connection kicks off the type's install or OAuth flow. The user-managed types today (Slack, GitHub, Neurocad Passport) are all OAuth-style — you don't paste tokens; you authorize the flow and Neurocad captures the credentials on callback.
Click an existing connection to open the per-connection page (/connect/[id]). This is where you see status, when it was added, who added it, the credential id, and where you can Reconnect (re-runs the OAuth/install flow) or Remove it.

Removing a non-managed connection prompts a destructive confirm ("Any recipe node still referencing this credential will fail to run until you reconfigure it."), calls the provider's revoke hook, then soft-revokes the connection so its history stays auditable. Recipes that reference the removed credential won't run again until you re-attach a different connection or Reconnect to refresh the same one.

Credential statuses

Every connection carries a lifecycle status. Five values, with a status reason and timestamp shown alongside on the connection page:

active — Fully authenticated, ready to use. No action needed.
needs_reauth — Token refresh failed or the provider explicitly asked for re-auth (Slack tokens_revoked, Passport invalid_grant). Click Reconnect.
uninstalled — A provider lifecycle event told us the install is gone (Slack app_uninstalled, GitHub installation.deleted). Add the connection again.
revoked — A user disconnected this connection from /connect. Add or pick a different connection.
error — A non-recoverable error during refresh. Reconnect; if it persists, contact support.

Recipes referencing a credential that isn't active will fail at deploy time with a WORKFLOW_CREDENTIAL_GRANT error. The Reconnect path is always the right first move — it preserves the credential id (so existing recipes keep working) and refreshes the underlying tokens.

Credential types in the system today

Five types currently ship. Two are user-created, two are platform-managed, one is runtime-only.

User-created — visibility: org

Every editor in your organization can see and select these connections in the canvas. Adding one makes it available org-wide.

Slack (slackApi)

OAuth v2 workspace install. Installs the Neurocad Slack app and captures a bot token scoped to the workspace.
Used by Slack action nodes and the Slack trigger.
Bot tokens don't expire; the connection only flips to needs_reauth if Slack delivers tokens_revoked, or to uninstalled on app_uninstalled.
Detail and setup steps live in the Slack integration doc — including the bot-invite-to-channel and /neurocad link requirements.

GitHub (githubApi)

GitHub App install. Installs the Neurocad App on a user or organization account and captures the installation id and short-lived installation access token.
Used by GitHub action nodes and the GitHub trigger.
Installation tokens last one hour and are refreshed transparently before each request through the platform's signed App JWT — nothing for the user to do.
The connection only flips to uninstalled if someone removes the App on github.com.
Detail and setup steps live in the GitHub integration doc — including the per-repository access model.

User-created — visibility: private

Listed only to the owner. Bound to recipes by an explicit owner-issued grant — see the next section.

Neurocad Passport (neurocadUserIdentityApi)

A user-owned, refreshable Neurocad identity. Authorising it captures a Cognito refresh token, an access token, and an identity token bound to your Neurocad user id.
Used by Library, Schematic, Create share link, and Send to desktop. Every one of those nodes runs as the passport owner — they create assets in that user's account, post share links under their identity, and send to that user's connected desktop.
The Passport refreshes itself: when the identity token is within a minute of expiring, the credential refreshes the Cognito access token (via the refresh token), then exchanges it for a fresh identity token and updates the stored credentials. If the refresh token is invalidated (Cognito invalid_grant / invalid_token, 401, 403), the connection flips to needs_reauth and the user has to click Reconnect.
This is the credential the preset notes mean when they say "Library and Schematic require a Neurocad Passport. Navigate to /connect and add one."

Platform-managed — visibility: org, managed

These show a Managed badge in /connect. There is no Add button, no Remove button, no editing form. The platform provisions a connection for your org from operator config and the runtime resolves it by org and type — workflow JSON never carries their ids. They behave identically to user-created credentials at execute time, just without a UI to edit them.

Neurocad Service (serviceApi)

Backs the EDA and Mechanical extraction services. Provisioned with machine-to-machine client material and service base URLs for your org.
Used internally by Library and Schematic alongside the Passport. The Passport supplies who the request is on behalf of; the Service credential supplies the M2M trust to call the upstream service.
Authors don't pick this credential — picking the Passport pulls the Service credential in automatically through delegation.

Neurocad Desktop Service (neurocadDesktopApi)

Backs the Send to desktop node by talking to the Neurocad desktop session-manager.
Provisioned with the session-manager base URL.
Same delegation pattern: the Passport supplies user identity, this credential supplies the route to the user's connected desktop.

Runtime-only

Webhook Source (webhook_source)

Used by the Webhook trigger (coming soon) to verify HMAC signatures on inbound webhooks.
Hidden from the Connect directory because there's no user create/edit experience yet.

Visibility, ownership, and the grant model

Two visibility modes drive who can see and use a credential:

org (default) — Every workflow editor in the org can see and select the credential in the picker. This is how Slack, GitHub, and the managed Neurocad credentials work. Selecting an org-visible credential at authoring time is enough; deploy-time checks just verify it still exists and is active.
private — Only the owner sees the credential in the picker. Selecting it requires an explicit grant recorded against the workflow node. Today the Passport is the only private type.

Why private? A Passport binds your real Neurocad identity to whatever recipe uses it. A workflow with your Passport on a Library node is creating Library results in your account, posting your share links, and routing to your desktop. So the platform requires that the Passport's owner is the one wiring it onto a node — you can't pick someone else's Passport and you can't bind yours invisibly.

At deploy time, the platform pre-flights every credential reference in the snapshot. For private credentials it walks a tighter path. The pre-flight errors you can hit:

Credential not found — The credential id in the snapshot doesn't exist (deleted? wrong org?).
Credential type does not match the node's slot — The credential the node was wired to is the wrong type for this slot.
Credential is needs_reauth / revoked / uninstalled / error — The connection isn't active. Reconnect before deploying.
Credential has no delegated subject — The Passport is missing its identity binding — typically a partial OAuth callback. Reconnect to repopulate.
Only the passport owner can grant it — Someone other than the owner is trying to deploy a recipe that references this Passport. The owner needs to deploy, or you need to pick your own Passport in the affected node.
Missing active grant — At runtime, the workflow has no active grant for the Passport (e.g. the owner left the org, or the grant was revoked).

All of these surface as a 409 WORKFLOW_CREDENTIAL_GRANT with the suggested action "Reconnect or select a passport you own, then deploy again."

Which credentials each node needs

Quick reference:

Slack trigger — Slack
Slack (action) — Slack
GitHub trigger — GitHub
GitHub (action) — GitHub
Library — Neurocad Passport (Service is delegated automatically)
Schematic — Neurocad Passport (Service is delegated automatically)
Create share link — Neurocad Passport
Send to desktop — Neurocad Passport (Desktop Service is delegated automatically)
HTTP request (coming soon) — Optional; pick from any of the above as auth
Webhook trigger (coming soon) — Webhook Source

Triggers, Local nodes, Control nodes, and Note do not need credentials.

When you select a node that needs a credential, the property panel shows a Credential picker at the top. The picker lists every connection of the right type that you can see — for org credentials that's all of them, for private credentials it's only the ones you own. Managed credentials can't be re-selected; they show a Managed badge and no chooser. If a node has a single managed credential available, the picker is zero-click — the connection is already bound.

Setting up a credential

The high-level flow is the same for every user-created type:

Go to /connect → click the type's card → Add connection.
The browser is redirected to the provider's authorisation page.
Approve. The provider redirects back to /api/<type>/oauth/callback. Neurocad exchanges the code, captures whatever metadata the provider returns (workspace name, account login, identity sub), and stores the credential.
You land back on /connect/provider/[type] with the new connection in the list.

What's stored differs by type — Slack stores a long-lived bot token plus the team id; GitHub stores an installation id, account id, and a short-lived installation token; Passport stores a refresh token plus access token plus identity token. None of the secret material is ever sent back to the SPA — the Connect API enforces this and refuses to write any credential payload that contains a credentials field.

Common scenarios

A recipe says it needs a Passport but the picker is empty. You haven't added one yet. Go to /connect → Neurocad Passport → Add connection. Or, you've added one but it's needs_reauth / revoked — open the connection and Reconnect.

Someone else's recipe deploys with the error "only the passport owner can grant it". The recipe was wired with a Passport you don't own. Either ask the owner to deploy it, or change the affected node to use your Passport.

Slack recipes stopped working with missing_scope. The Slack app's bot scopes changed since this connection was created. Go to the Slack connection and Reconnect — Slack will prompt for the new scopes and the credential will refresh in place.

GitHub recipes 404 on a repo you can see in github.com. The GitHub App isn't installed on that repo (or that repo was excluded from the install). Manage the install on github.com → Settings → Installed GitHub Apps → Neurocad → Configure → add the repo. No change needed in /connect.

The Connect card shows "Reconnect required". A previous connection drifted into uninstalled / revoked / error. Click into the type, open the dormant connection, and Reconnect — preserves the credential id so existing recipes pick up the refresh.

The Connect card shows "Managed" with no count. That's fine — managed types don't show a count, just whether they're provisioned. Recipes will resolve the credential automatically through the org-managed runtime path.

You disconnected a credential by accident. Re-add it from the same /connect/provider/[type] page. The new connection gets a new id, so any recipe that referenced the previous one needs to be updated to reference the new id.

Quick checklist when something credential-shaped is wrong

/connect shows the credential as active, not needs_reauth / uninstalled / revoked / error.
The recipe references your Passport (or the right org connection) — not a deleted or someone-else-owned one.
For Slack: the bot is invited to the channel; for GitHub: the App is installed on the repository.
For deploy errors: the credential mentioned is owned by the deployer (Passport) or visible to the org (everything else).
If Reconnect isn't fixing it, Remove and Add connection to start clean — recipes will need their credential references re-pointed at the new id.

If all of those pass and execution still fails on a credential, the failure is downstream of /connect — usually missing repo access (GitHub), missing channel membership (Slack), or an upstream provider outage. The error message in the run data panel will name the specific provider error.