Authentication

The BioNodulo cloud API authenticates with Clerk, the same identity system that powers sign-in at cloud.bionodulo.com. There are no user-managed API keys — programmatic access rides on the same session the app uses.

How the app authenticates

Signing in (email, OAuth, or SSO) creates a Clerk session. The cloud dashboard and editor call the API same-origin, sending the Clerk session cookie automatically — no token handling in your code.

How API consumers authenticate

From a script, CI job, or the desktop/local app (a different origin, where the session cookie is not sent), present a Clerk session JWT as a bearer token:

curl https://bionodulo.com/api/workflows \
  -H "Authorization: Bearer $BIONODULO_SESSION_TOKEN"

The server verifies the token against Clerk and rejects tokens minted for a different frontend of the same Clerk instance (audience-confusion protection). The desktop app instead signs in with a Clerk OAuth 2.0 PKCE flow and presents the resulting access token (oat_…) the same way; the server verifies it with Clerk’s Backend API and rejects expired or revoked tokens.

Team context and X-Team-Id

Almost every endpoint operates on a team (a Clerk organization):

• Cookie path — the active organization comes from the session. Switch teams in the dashboard to change context.
• Bearer path — the JWT carries no active-organization claim, so the server picks your team for you: your first membership (or a team you own). To choose explicitly, send the internal team id:

curl https://bionodulo.com/api/billing/credits \
  -H "Authorization: Bearer $BIONODULO_SESSION_TOKEN" \
  -H "X-Team-Id: <teamId>"

Membership in the requested team is verified; a team you don’t belong to returns 403.

Token lifetime and refresh

Clerk session tokens are short-lived JWTs that the app refreshes continuously while you’re signed in; signing out revokes the session immediately. Scripts should obtain a fresh token per run (or re-fetch on a 401) rather than cache one — an expired token returns 401, never partial data.

Share-link invite tokens

Per-workflow share links mint invite tokens (bni_…). A guest holding an editor-role invite may present it as the bearer token on POST /api/runs to run that workflow, billed to the owning team — no account required. See REST API Reference — Sharing.

Roles and permissions

Within a team, roles are owner, admin, member, viewer. Viewers are read-only (no runs, uploads, or deletes); only owners/admins manage billing and invites. A permitted-looking request from an under-privileged role returns 403.

Errors

Next

• REST API Reference
• WebSocket Events