Authentication

Every Nodaro API request authenticates with a bearer token in the Authorization header. Use a personal API token (ndr_…) when your own server calls Nodaro for your account, an OAuth access token (ndr_app_…) when your product acts for other Nodaro users, and your session JWT on a self-hosted Community Edition install.

Authorization: Bearer ndr_4f1c…

Which credential to use

A quick test: if your server needs one set of credentials and no consent screen, use an API token. If many customers must each give your app access to their own account, use OAuth.

API tokens are available on Nodaro Cloud and on the Business edition. On the Community Edition, call the same endpoints with the access token of your signed-in session instead. See Editions.

Create an API token

The page lists each token with its name, its prefix, its rate limit, when it was last used and when it was created. The switch next to a token turns it on or off, and the trash button deletes it.

Rules for API tokens

• Up to 10 tokens per account, active or not. A deactivated token still counts, so delete it to free the slot. An eleventh token is refused with 400 limit_reached.
• No expiry and no spend cap. A token works until you deactivate or delete it. Deleting a token revokes it immediately.
• The token acts as you. Every call it makes runs as your account and spends your credits.
• It is not re-checked against your sign-in provider. A token created before your account was removed from an identity provider keeps working until you revoke it. Treat every token as a permanent credential.

Limit a token to some workflows

A token can be limited to a list of workflows, its workflow scope. A token made on the API Tokens page has no scope: it can run every workflow you own. A token with no workflowIds is the account's full-access token.

Set the scope with the workflowIds field, up to 50 workflows, when you create or update a token through the endpoints below. A change to the scope applies within a minute. Only workflows in your personal space can be listed: a workflow that lives in a workspace answers 400 invalid_workflow.

A scoped token is for running its workflows. It can run them, read them and their inputs, and follow their runs, and nothing else:

• GET /v1/api/workflows, GET /v1/workflows and GET /v1/projects/:projectId/workflows list only those workflows. GET /v1/executions lists only their runs.
• GET /v1/api/schema, POST /v1/api/run, GET /v1/workflows/:id, GET /v1/workflows/:id/interface, POST /v1/workflows/:id/run, POST /v1/workflows/:id/render-final/estimate and GET /v1/workflows/:id/executions answer for those workflows only.
• GET /v1/api/status/:execId, GET /v1/api/result/:execId and GET /v1/workflow-executions/:id, with its /stream and /cancel routes, answer for runs of those workflows only. A run that is not yours answers 404.
• Routes that need no sign-in, such as the public gallery and the model and node catalogs, answer as they do without a token.

Every other request answers 403 forbidden, with the message "This API key is limited to specific workflows, and this request is outside them. Use a key without a workflow limit for anything else." That covers another workflow or its runs, editing or deleting a workflow, the direct generation routes, uploads, jobs, published apps, MCP, and use as a relay credential. The request is refused before anything runs, so nothing is reserved or billed.

Manage tokens from code

These four routes work only from a signed-in session, so send your session JWT, not an API token. A personal API token or an OAuth token is refused with 403 forbidden, with the message "API token management is only available from a logged-in session". On a Community Edition install, the create and list routes answer 403 edition_required with required_edition: "business".

To bind a token to one workspace, see Bind a token to a workspace.

Send the token

GET /v1/me returns the account behind any valid token, so it is the quickest way to check a token. A missing, invalid or revoked token answers 401 unauthorized.

curl https://app.nodaro.ai/v1/me \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
    "email": "ada@example.com",
    "displayName": "Ada",
    "avatarUrl": null,
    "tier": "pro",
    "isAdmin": false
  }
}

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const me = await client.me()
console.log(me.email, me.tier)

nodaro auth login --token "$NODARO_API_KEY"
nodaro auth status

On an account that belongs to an organization, the same response also carries the organizations and workspaces the account belongs to. See Workspaces and organizations.

The SDK takes the token from an auth provider, so you choose how the token is found:

The CLI saves the token in ~/.config/nodaro/config.json with file mode 0600. Add --profile and --base-url to keep a second login for a self-hosted install, for example nodaro auth login --profile local --base-url http://localhost:3000.

OAuth access tokens

Use OAuth when each of your users connects their own Nodaro account to your product. Your server exchanges an authorization code for an access token that starts with ndr_app_. The token lives 90 days, and there are no refresh tokens: after it expires, send the user through the consent screen again.

An OAuth token carries only the scopes the user granted. A route that needs a scope the token lacks answers 403 insufficient_scope, and the error names the scope in missingScope. The scopes most API integrations need:

Personal API tokens and session JWTs have no scopes: they act as your own account. Read the full flow, every scope and the consent screen in OAuth apps, and the scopes of the app routes in Managing published apps.

Routes that need a signed-in session

A few routes exist for the Nodaro web app and refuse both API tokens and OAuth tokens:

To build workflows from code, use the workflow endpoints, the SDK or the MCP server.

Identify your client

Send an X-Nodaro-Client header and Nodaro records it as the origin of every job the request creates:

X-Nodaro-Client: sdk/1.10.0

Only three forms are recognized: sdk/<version>, cli/<version> and extension/<name>. Any other value is ignored, because the header is not authenticated. @nodaro/sdk and @nodaro/cli send it for you, so you need it only when you call the REST API directly. Omitting it is fine: those jobs are recorded as generic API calls.

Browser callers should not send the header. The browser's Origin header already names the site, and Nodaro prefers it. The SDK leaves the header out automatically when it runs in a browser.

Keep tokens on your server

A token in browser code is readable by anyone with developer tools, and it can spend your credits. Keep the token in a server route, an edge function or your platform's secret store, and let the browser talk only to your server:

Browser  ->  your server (holds NODARO_API_KEY)  ->  Nodaro API

In Next.js, for example, read the token in a route handler from an environment variable without the NEXT_PUBLIC_ prefix. If you do call Nodaro from a browser with an OAuth token, add your site's origin to the developer app's allowed origins.

Connect a self-hosted install with a token

A personal API token without a workflow scope is also the simplest way to run a self-hosted install's generations on Nodaro Cloud. On the self-hosted install, set NODARO_CLOUD_URL to the Nodaro Cloud address and NODARO_API_KEY to your token. Every generation then runs on Nodaro Cloud and is billed to the token's account, with no OAuth connection. See Connect to Nodaro Cloud.

Deployments with one billing account

Some deployments have a single billing account that pays for every user. On those deployments:

• Only the billing account can create a token. Anyone else gets 403 api_tokens_payer_only, and existing tokens stay listable and revocable by their owners.
• The API Tokens card is not shown in Settings. The billing account opens /settings/api directly.
• Every call a token makes is paid from the deployment's pool.
• A token cannot read that pool. Balance reads made with the billing account's token answer 403 payer_balance_jwt_only, and the deployment billing routes answer 403 payer_required.

Errors

Every error uses the same envelope. See Errors for the full list.