Workspaces and organizations

Workspaces are where an organization's members work together: a class in a school, a team in a company. An API request acts in one workspace when you send its id in the X-Nodaro-Workspace header, and the organization endpoints manage everything around it: organizations, members, invitations, join codes, sharing, budgets and usage.

Organizations are a Nodaro Cloud feature and are switched on per instance. Where they are not enabled, the endpoints below do not exist and the header is ignored. Self-hosted builds do not include organizations. Read Workspaces for the concepts.

Act in a workspace

X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34

The header does two things, and only these two: it decides which workspace a list returns and where a create lands. It never grants access. Reading, updating, deleting or running something you name by id follows that object's own workspace. A forgotten header cannot hide your work, and a forged one cannot reach anyone else's.

Without the header you work in your personal space, as an account without an organization always does.

curl -s https://app.nodaro.ai/v1/workflows \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "X-Nodaro-Workspace: 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"

// Every request of this client acts in the workspace:
const classClient = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
  workspaceId: '6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34',
})

// Or derive a second client from an existing one:
const classroom = client.withWorkspace(workspaceId)
await classroom.workflows.run(workflowId) // lands in the class
await client.workflows.run(workflowId)    // lands in the personal space

nodaro --workspace 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34 workflows list   # this command only
export NODARO_WORKSPACE=6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34            # this shell or CI job
nodaro workspace use 6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34                # saved on the profile
nodaro workspace current                                                # which one applies, and why

client.withWorkspace returns a new client instead of changing the old one, so two operations running at the same time can never race over which workspace they are in. Pass null for the personal space. In the CLI, each of the three ways beats the one below it, and nodaro workspace use checks the workspace before saving it.

Send the header only for a workspace you belong to:

Two places never refuse a stale selection, so it can never lock you out: GET /v1/me and GET /v1/workspaces, and accepting an invitation. There, a workspace you can no longer select is treated as if you sent no header. Those are the endpoints that tell you which workspaces you may select, so clear a cached selection when they stop listing it.

Bind a token to a workspace

An API token can be bound to one workspace. It then acts as if it sent the header on every request, and an explicit header naming a different workspace answers 400 token_workspace_mismatch.

# Bind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "6f1e6b4c-6a4e-4b7b-9d2a-2f0f0a1d9c34"}'

# Unbind
curl -X PATCH https://app.nodaro.ai/v1/api-tokens/$TOKEN_ID \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": null}'

Token management needs your signed-in session's JWT: an API token or an OAuth token gets 403 forbidden. You can bind a token only to a workspace you could select with the header, and unbinding is always allowed. Listing your tokens returns the binding as workspaceId.

Where a create lands

• Inside a workspace, a create lands in the workspace, never in your personal space. A create that names no project goes to the workspace's project. When the workspace has no project yet, the create answers 409 workspace_has_no_default_project: name a project and it succeeds.
• A project you name must belong to the workspace you act in. A project of another workspace, or of your personal space, answers 404 Project not found. That is the same answer as a project that does not exist, so the header cannot be used to discover what exists.
• Creating a project may be limited to admins. Members then get 403 project_create_not_allowed.
• An organization can close the personal space. Its members then create only inside a workspace, and a create without the header answers 403 personal_space_disabled. Accounts without an organization are never affected.

Archived workspaces are read-only

Archiving a workspace keeps everything in it readable and stops new work from being added. Lists behave as before. Every create, whether a project, a workflow, an import or a sub-workflow, answers 409 workspace_archived, and so does moving work into the workspace. Moving work out stays allowed, because rescuing it is the reason to open an archived workspace. Other writes into it, such as sharing a workflow, answer 403 workspace_archived. Match on the code, not on the status.

Who you are: GET /v1/me

GET /v1/me returns your profile. On an instance with organizations it also carries organizations, workspaces and lastWorkspaceId, each entry with your own role and status. Organization entries include the resolved vocabulary, such as the word the organization uses for a workspace, so a client never hard-codes "Class" or "Team". GET /v1/workspaces returns the same workspace list on its own.

Keep the three states of the organization fields apart:

Organization endpoints

Every endpoint needs authentication. Bodies are JSON, responses are { "data": … }, lists are { "data": [ … ], "nextCursor": … }, and ids are UUIDs.

Organizations

• Approval. A new organization usually starts pending and becomes active once the platform approves it. Its owner sees it while it waits, nobody else does, and nothing in it can change. Tell whoever created it, or the wait looks like a failure.
• Schools need terms. Creating a school requires acceptTerms: true, by which the owner confirms the authority to enroll students. Without it, the create answers 400 terms_required.
• Slugs are 1 to 50 lower-case letters, digits and hyphens. A slug you send must be free (409 name_taken). Without one, it is derived from the name: "Sunrise School" becomes sunrise-school, then sunrise-school-2.
• Creating organizations is limited to a few per hour for each user.

Members

Workspaces

Workspace members

Organization owners and admins are admins of every workspace in the organization without being listed. Adding one of them to a workspace explicitly gives them that explicit role instead, which is how an organization admin can be a plain member of one class.

Invitations

An invitation names one email address. Its link carries a token that exists only in the email, and the invitee sees what they are invited to before signing in.

• Each address gets its own row. status is sent, link_only or failed, and link is present whenever the address was not emailed. An install without a mail provider returns every address as link_only. Show those links: the invitation exists either way, and without the link nobody can reach it.
• Invitations expire after 14 days, and an organization may send 500 a day (429 bulk_invite_cap_exceeded).
• Inviting an address again moves its open invitation to a fresh token instead of creating a second one.
• Inviting an existing member uses up the invitation but does not change their role or lift a suspension.

Join codes

A join code is eight characters, short enough to read aloud in a room. It admits a plain member into one workspace, never lifts a suspension, and respects the organization's allowed email domains.

Sharing one workflow

A grant gives one person access to one workflow. It can only add access, never remove it.

• Who may share: the creator; a workspace admin where admins may edit members' work; and anyone who may edit the workflow where the workspace lets collaborators invite.
• Adding by email matches any account's address, whatever its organization. 404 means there is no account, and nothing more is disclosed.
• Someone outside the workspace is capped at viewing, even with an editor grant. Running needs active membership, so an outside collaborator can never spend the workspace's credits.
• You cannot grant to the workflow's creator or to yourself (400). A grant works at once, with no acceptance step.
• canChangeVisibility, canShare and canRun are three separate rules. Never infer one from another.

A workflow you cannot reach at all answers 404, the same as one that does not exist. Only when you can already see it and need more does the answer become 403. Running a workflow that belongs to a workspace needs edit access and active membership.

Audit log

The audit log stays readable while the organization is suspended. action is an open list that grows with the product: show the actions you know, and fall back to the raw value for the rest.

Roles and settings

Settings are layered: a workspace's setting wins over the organization's, which wins over the default for the organization's kind. A key that is not set falls through, and false is a real value.

The organization alone also has allowed_email_domains, such as ["school.example"], and vocabulary_overrides, such as { "workspace": "Cohort" }. Both are replaced whole when updated.

A school starts with: admins edit, workflows private, members view shared work, members cannot create projects, caps on, personal space on, workspace admins can invite, collaborators cannot. A team starts with: admins view, workflows visible to the workspace, members edit shared work, members can create projects, caps off, personal space on, and both invite settings on.

Budgets and usage

An organization pays for its members' work in three steps, each narrower than the last:

1. The pool. The organization buys prepaid credit packs into one pool for the whole organization, through its own checkout.
2. Allocations. The owner moves credits from the pool into a workspace's budget. The pool goes down by exactly what the workspace gains. Credits can go back to the pool, but only down to what the workspace has already reserved or spent.
3. Member caps. Inside a workspace, an admin can cap what one member may spend. Caps apply only where the workspace's settings turn them on, and never to an organization admin working in the workspace.

Work done inside a workspace is paid by the workspace, and the member's own credits are not touched. Headroom at every level is allocated minus reserved minus spent, and a run that would exceed it is refused with 402 budget_exceeded or 402 member_cap_exceeded before it starts.

Refunds and disputes take credits back from the organization's pool in proportion, never below zero. Deleting an organization requires taking back every workspace allocation first.

Automations spend the workspace's credits. A Webhook Trigger URL is a bearer credential: whoever holds it can start a run, and a run of a workflow in a workspace is paid by that workspace. Every automated run, from a webhook, a schedule or Telegram, checks first that the trigger's creator may still run the workflow. When they no longer can, the automation stops and the run history shows one failed entry with the code run_requires_authenticated_member.

Usage reports

The two usage routes answer who spent how much on what, over a date range:

• Each row has three credit figures. credits is what the runs cost so far: the settled amount for finished runs and the held reservation for runs in flight. settledCredits and inFlightCredits split that sum.
• A metered run that cost more than the workspace had left is charged up to the headroom, and the platform absorbs the rest. The totals report it as platformAbsorbedCredits, and settledCredits minus platformAbsorbedCredits is what reached the budget. An approved-app markup the budget could not cover is absorbed too and reported apart as appMarkupAbsorbedCredits.
• A report with more than 5,000 groups returns truncated: true. Only the grouped rows are cut: the totals cover the whole range.
• A plain member sees only their own runs, and grouping by member is refused for them. A workspace admin sees everyone and may filter by userId. The organization report is for owners and organization admins.
• CSV exports are UTF-8, RFC 4180, with CRLF line endings and no byte-order mark. A cell that starts with =, +, - or @ is quoted with a leading apostrophe so a spreadsheet cannot run it. Exports are limited to 10 per minute for each user and are recorded in the audit log.
• When a member deletes their account, their run history goes with it, and the report shows a gap. Their workflows and projects stay with the workspace.

An instance without usage reports answers 404, and 503 billing_unavailable while reporting is not yet available.

Errors

From the SDK, the CLI and MCP

• SDK: client.organizations and client.workspaces cover these endpoints, including usage, usageRows and usageCsv for reports. client.me() carries the organization fields.
• CLI: nodaro org and nodaro workspace, for example nodaro org invite <orgId> --email ada@school.example --workspace <id> and nodaro org usage <orgId> --from 2026-09-01 --to 2026-09-30 --group-by member --csv > september.csv. The invite command prints one line per address, with the link for any address that was not emailed.
• MCP: the list_workspaces and select_workspace tools. The selection is remembered across sessions and checked again at each one. An OAuth app that uses these tools needs the workspaces:read and workspaces:write scopes.

Read The CLI and The SDK for the full command and method lists.