Access tokens and API calls

Create the right key, scope it to your project, and verify an authenticated request.

Use a bearer token when a backend, script, or MCP client needs to call Octonode without a browser session. Keep private tokens on the server or in your local credential environment.

Choose a token

Credential	Intended use	Boundary
Personal access token	Scripts acting as you	Your current account permissions, limited by token scopes
Service token	A workspace integration	Bound workspace and scopes; cannot exceed its creator's access
Project API key	A project integration or agent	Selected project, scopes, and expiry
Public browser token	Intentionally public data in a website	`data:read` with exact allowed HTTPS origins

Public browser tokens are visible to visitors. Allowed origins help control browser usage, but an HTTP client can forge an Origin header. Do not use public tokens to protect confidential data; keep those requests behind a backend with a private key.

Create and store a key

For personal, service, and public tokens, open Settings → Access tokens in Studio, choose the token type, and give it a recognizable name. Service and public tokens use a workspace; public tokens also need exact origins such as https://app.example.com, without a trailing slash or wildcard.

For project access, use the project's API keys settings. Choose the actions and expiry your integration requires. Creating workspace or project service credentials requires permission to manage agents (agents:manage).

Copy the secret when it is created: the token list shows its identifying prefix, not the complete secret. Save it in a secret manager or a local environment file excluded from version control. Do not paste it into an assistant prompt or a public client bundle. Revoke a lost or exposed key and create a replacement.

Token management requires a signed-in session; an existing API token cannot mint another token. An account service must be available for these settings. A local deployment without one can report 503 for token management.

Select permissions

Action	Enables
`projects:read`	Inspect project files, nodes, and workflows
`projects:write`	Edit source and workflow structure; compile and synchronize
`workflows:run`	Execute and cancel workflows

Grant only the actions needed by the integration. A prompt asking an agent to "only read" is useful guidance, but a read-only key enforces the boundary. Other API features may require additional action scopes.

Verify your connection

Make these values available in your shell's environment. Replace the example workspace and project IDs with the values from your project settings. OCTONODE_API_TOKEN must hold the private key you saved; the commands below never print it.

export OCTONODE_API_URL="http://localhost:4000"
export OCTONODE_WORKSPACE="user:YOUR_USER_ID"
export OCTONODE_PROJECT="YOUR_PROJECT_ID"

Use the actual API origin for a hosted deployment, including https://. The base URL excludes /api. Workspace values have the form user:ID, org:ID, or team:ID. The Playbook preview on port 4200 is a documentation site, not your API.

curl --fail-with-body --get \
  "$OCTONODE_API_URL/api/projects/$OCTONODE_PROJECT/settings" \
  --data-urlencode "workspace=$OCTONODE_WORKSPACE" \
  -H "Authorization: Bearer $OCTONODE_API_TOKEN"

A successful response is JSON for the selected project's settings. This is a read-only check. Include the explicit workspace on scoped API requests.

Call from a Node.js backend

This standalone example uses Node.js 24's built-in fetch. Save it as check-connection.mjs and run node check-connection.mjs in the same environment.

const { OCTONODE_API_URL, OCTONODE_API_TOKEN, OCTONODE_WORKSPACE, OCTONODE_PROJECT } = process.env;
if (!OCTONODE_API_URL || !OCTONODE_API_TOKEN || !OCTONODE_WORKSPACE || !OCTONODE_PROJECT) {
  throw new Error("Set the four OCTONODE connection variables first");
}
const url = new URL(`/api/projects/${encodeURIComponent(OCTONODE_PROJECT)}/settings`, OCTONODE_API_URL);
url.searchParams.set("workspace", OCTONODE_WORKSPACE);
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${OCTONODE_API_TOKEN}` },
  redirect: "error",
});
if (!response.ok) throw new Error(`Octonode returned HTTP ${response.status}`);
console.log(await response.json());

The node-authoring SDK does not provide account login. Use the HTTP API for remote requests and the TypeScript SDK to implement nodes. For workflow execution requests, continue with inputs and HTTP calls.

Diagnose authentication failures

401: the key is missing, expired, revoked, or belongs to another deployment.
403: check the action scopes, current workspace membership, and project binding.
404: check the API origin, route, and project ID. Confirm that the project is visible in the selected workspace.
HTML instead of JSON: the URL may point to the documentation site or a frontend fallback instead of the API.

When rotating a key, update every consumer, verify a read, then revoke the old key.