Authentication & API keys

Every request to Neuronz.ai is authenticated. There are three ways to sign in:

• Dashboard session — you, signed in to the web app. Email and password sign-in requires a verified email address; see Create your account and Reset your password.
• Harness sign-in — your harness (the coding agent you use: Claude Code, the Claude desktop app, or Oh-My-Pi) signs in through your browser. The Neuronz.ai tools and the plugin's automatic steps then run as you.
• API keys (nzk_…) — credentials for CI jobs, scripts and agents that run with no person present. Sent as Authorization: Bearer nzk_….

Harness sign-in

Harness	Sign in	Sign out
Claude Code	/neuronzai:login	/neuronzai:logout
Claude desktop app, Code tab	/neuronzai:login	/neuronzai:logout
Claude desktop app chats and Cowork tasks, claude.ai	Connect on the Neuronz.ai connector — see Claude desktop app	Disconnect the connector
Claude mobile app	Connect on the Neuronz.ai connector — see Claude mobile app	Disconnect the connector
Oh-My-Pi	/neuronzai:login	/neuronzai:logout

/neuronzai:login opens your browser on Neuronz.ai. Approve the sign-in and go back to your harness. You never paste a password or token into the conversation.

On a machine with no browser, sign-in uses two steps instead: it prints a link, you open it on any device that can reach Neuronz.ai and approve, and you paste back the one-time code the page shows. That code only works once, and only on the machine that started the sign-in. See the exact steps for Claude Code and Oh-My-Pi.

The plugin stores your sign-in in the operating system's credential store:

• Linux uses the desktop keyring (Secret Service, through secret-tool) when one is available.
• macOS uses Keychain.
• Windows uses DPAPI.
• If none is available, it falls back to a private file in your Neuronz.ai config directory that only your user can read.

The sign-in renews itself and survives restarts of your harness. /neuronzai:logout revokes it on the server and removes it from your machine, even if the server is unreachable at that moment.

If you have not signed in, the plugin shows a reminder at the start of each session that persistent memory (recall, rules and capture) is off until you run /neuronzai:login. The check runs on your machine, so a server outage never triggers it.

If the NEURONZAI_API_KEY environment variable is set where your harness runs, the plugin uses that key instead of your browser sign-in. Unset it to go back to the browser sign-in.

API keys

Use an API key when no person is present at all, such as in CI. A remote machine you are working on does not need one: sign in there with the two-step flow above.

Create and revoke keys in the dashboard under Security → API keys. The key is shown once, when you create it; copy it then, because it cannot be shown again. Revoking a key takes effect immediately.

When you create a key, choose its Permissions:

• Read-only — can read but never write. Use this for agents that run without you.
• Read & write — the default.
• Admin — read and write, and can also create and revoke API keys.

Read-only keys

A read-only key can use every tool that reads — recall, fact_search, search, read_rules, every get_* and list_* — and is refused by every tool that writes: fact_add, add_knowledge, log_action, create_rule, kv_set, every update_* and delete_*, resolve_conflict, and the rest. Use one for an agent that should read your context (knowledge, facts) but never change it: a CI code reviewer, a scheduled job, any agent working on input you don't fully control.

A read-only key also never creates a profile. A lookup from a directory Neuronz.ai does not know returns nothing, where a read-write key would create a new profile for that directory.

A refused write returns this error, which the agent sees and can work around:

{"error":"read_only_token","error_description":"This credential is read-only (scope 'read') and cannot perform writes. Use a read-write key to mutate."}

A read-only key shows a read-only badge in the dashboard.

Recipe: an agent with no person present

Create a read-only key, store it as NEURONZAI_API_KEY in the agent's environment, and add Neuronz.ai to the agent's MCP configuration with the key as a header:

{
  "mcpServers": {
    "neuronzai": {
      "type": "http",
      "url": "https://app.neuronz.ai/mcp",
      "headers": { "Authorization": "Bearer ${NEURONZAI_API_KEY}" }
    }
  }
}

The agent can then call the read tools; every write tool returns the error above.

Your account and workspace

Every account gets exactly one personal workspace, created automatically when you sign up. Neuronz.ai is for individuals: you cannot create additional organizations, invite other members, or delete your workspace. Your plan is set by Neuronz.ai and cannot be changed from the dashboard.

Rate limits

Neuronz.ai limits how fast a single client can call it. When a limit is hit, the request is refused with 429 Too Many Requests and a Retry-After header giving the number of seconds to wait.

What	Limit
Sign-in attempts	10 per 5 minutes, per IP address
Sign-ups	5 per hour, per IP address
Password-reset and verification emails	5 per hour, per IP address
Password-reset and email-verification links	10 per 5 minutes, per IP address
Everything else	a per-minute budget per IP address, and a separate one per account

The general budget is far above what the plugin needs in normal use, including recall on every prompt and every tool call. The per-account budget is shared by everything signed in to your account (the dashboard, your harnesses and your API keys), wherever it connects from.

A throttled request answers:

{"error":"rate_limited","message":"Too many requests. Please slow down and retry later.","retryAfter":42}

On the sign-in page a throttled attempt shows "Too many requests. Please try again later." Wait a few minutes before trying again.