Authentication

Overview

Neuron uses three token types, each scoped to a different level. Understanding which token to use is the first step in any integration — dashboard work, bot-level API calls, and server-to-server automation each need a different credential.

Session Token (JWT)

Session tokens are JWTs issued when you log in to the dashboard or authenticate via the MCP server. They are user-level and org-scoped — the token carries your identity and the organization you are working in. The dashboard web app uses them automatically. The MCP server obtains one when you call neuron_login. Tokens are valid for 30 days and can be refreshed.

curl https://neuron-api.dlvh.site/api/v1/bots \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Bot API Key (nrn_)

Bot API keys are scoped to a single bot. They authenticate requests to the /api/v1/bot-api/* endpoints — chat, send, actions, conversations, and magic links. Create one from a bot's API Keys tab in the dashboard. Keys start with the prefix nrn_ and can optionally have an expiry date.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/chat \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

Account Token (nrn_acc_)

Account tokens are org-scoped and not tied to any particular bot. They authenticate requests to the /api/v1/account/* endpoints — contacts, contact lists, broadcasts, groups, newsletters, WhatsApp Status, campaigns, ads, and knowledge bases. Create one from Settings > Account Tokens. Keys start with the prefix nrn_acc_.

curl https://neuron-api.dlvh.site/api/v1/account/contacts \
  -H "Authorization: Bearer nrn_acc_your_token"

Which token do I use?

Match your use case to the right token:

1. 1

   Dashboard or MCP

   Use a session token. You get one automatically when you log in. For MCP, call neuron_login or set the NEURON_AUTH_TOKEN environment variable.

2. 2

   Bot chat, send, or actions

   Use a Bot API key (nrn_). Create one in the bot's API Keys tab. Scoped to that bot only.

3. 3

   Server-to-server (contacts, broadcasts, groups, newsletters)

   Use an account token (nrn_acc_). Create one in Settings > Account Tokens. Covers all org-level endpoints.

Token Security

Rotate tokens periodically and revoke any that may have been exposed. Bot API keys and account tokens can be revoked from the dashboard at any time. Session tokens expire after 30 days. Never log tokens in plaintext or commit them to version control.