Device JID: sensor@example.net
```
The account must be able to communicate with the device, and the device's provisioning rules must allow sensor readouts. An address alone does not grant access.
## 1. Load the client libraries
Create a development page served over HTTPS:
```html theme={null}
Open the browser console and run the example.
```
For a page on another origin, the Neuron must allow that origin. Set the API host before making requests:
```javascript theme={null}
AgentAPI.IO.SetHost("neuron.example.com", true);
```
## 2. Sign in
In the browser developer console:
```javascript theme={null}
await AgentAPI.Account.Login("", "", 3600);
```
The library keeps the JWT in browser session storage. Do not put the password or token in the page's source.
## 3. Read momentary fields
```javascript theme={null}
const result = await AgentAPI.Things.Sensor.ReadStandaloneDevice(
"sensor@example.net",
"en",
true, // momentary
false, // peak
false, // status
false, // computed
false, // identity
false, // historical
[], // all allowed fields
null, // from
null, // to
null // when
);
console.log(result.Fields);
console.log(result.Errors);
```
Success means `result.Fields` contains one or more values, or the device returns a valid empty readout. Preserve each field's timestamp, unit, type, and quality information.
## If the read fails
* **Authentication error:** confirm the Agent API login first.
* **Device unavailable:** verify the JID, roster relationship, and device connection.
* **Forbidden or empty result:** review provisioning for this account and field set.
* **Browser CORS error:** host the page on the Neuron or allow its exact origin.
Next, learn the [device model](/iot/device-model) before addressing concentrator nodes, or see [sensor data](/iot/sensor-data) before requesting historical or subscribed values.
# IoT security model
Source: https://docs.neuro-tech.io/iot/security
Layer identity, TLS, federation, consent, provisioning, P2P, and end-to-end encryption
No single mechanism protects a Neuro IoT interaction. Security is layered.
## Layers
| Layer | Protects |
| -------------------------- | ----------------------------------------------------- |
| SASL authentication | Entity connection to its XMPP broker |
| TLS transport | Each TCP/WebSocket/BOSH hop |
| Federation validation | Broker domain identity across S2S links |
| Roster/presence consent | Who may establish a social communication relationship |
| Tokens | Additional device, service, or user assertions |
| Provisioning | Owner-defined operation authorization |
| P2P authentication | Direct peer channel establishment |
| End-to-end encryption | Stanza content across brokers/intermediaries |
| Legal identities/contracts | Legally meaningful actors and agreed policy |
## Bindings
Clients can connect through supported XMPP bindings such as TCP, WebSocket, or BOSH depending on the implementation. Use a secure transport and validate the broker certificate/host name. Browser constraints do not weaken the authorization model.
## End-to-end encryption
The Neuro E2E interface publishes asymmetric key material, negotiates supported algorithms, and protects message and IQ stanzas with hybrid encryption. Supported families can include RSA, elliptic-curve and post-quantum algorithms, with AES-256 or ChaCha20/Poly1305 symmetric protection depending on endpoints.
Feature-detect algorithms, reject downgrade, rotate compromised keys, and bind keys to the authenticated peer.
## Federation
In federation, brokers validate each other's domains and forward stanzas between clients on different domains. An application must still authenticate the end actor and authorize the requested operation; a valid remote domain is not blanket trust.
## Threat checklist
* replayed commands and stale tokens;
* malicious or compromised broker/package;
* device claim-code theft;
* over-broad provisioning cache entries;
* prompt/script injection through sensor labels or messages;
* metadata/location leakage through discovery;
* unsafe control retries;
* lost key revocation and software-update signing keys.
# Sensor data
Source: https://docs.neuro-tech.io/iot/sensor-data
Represent typed fields and choose a real-time communication pattern
Sensor data consists of typed **fields** with timestamps, names, values, optional units, categories, quality flags, localization, and node identity.
## Field categories
Requests can select categories such as momentary, peak, status, computed, identity, and historical data. Ask only for categories and field names the application needs; unconstrained historical reads can be expensive.
## Communication patterns
| Pattern | Use when | Behavior |
| ------------------ | -------------------------------------- | ---------------------------------------------------------------------------- |
| Request/response | One current or bounded historical read | Immediate, delayed, scheduled, queued, fragmented, and cancellable responses |
| Event subscription | Notify when values meet trigger rules | Device maintains a subscription and sends sensor events |
| Publish/subscribe | Many consumers follow a stream | Data is published to an XMPP PubSub/PEP node |
## Request/response lifecycle
1. Send field/category, node, time-range, and optional token filters.
2. Receive an acknowledgement with request identity.
3. Process zero or more field fragments.
4. Stop only when the response marks completion or an error occurs.
5. Cancel the request when the result is no longer needed.
Do not assume all sensor reads fit in one stanza. Large or slow devices can stream fragmented results asynchronously.
## Quality and units
Preserve quality flags and timestamp with the value. Convert units through published unit definitions rather than hard-coded display conversions. Never compare readings from incompatible units or silently discard uncertainty/status fields.
## Subscription hygiene
* Use meaningful thresholds and minimum intervals.
* Renew/monitor subscriptions as required by the device.
* Unsubscribe when the consumer goes away.
* Deduplicate events by request/subscription identity and field timestamp.
* Apply backpressure or aggregation before forwarding high-rate telemetry.
For browser integrations through a Neuron, see [Agent Things API](/iot/agent-things-api).
# Federated software updates
Source: https://docs.neuro-tech.io/iot/software-updates
Discover, distribute, verify, and apply signed device packages without a central download bottleneck
The software-update interface lets devices discover and subscribe to signed package metadata through an XMPP service while package bytes can travel over HTTP(S), HTTP over XMPP, FTP, or another supported URI scheme.
| Item | Value |
| ---------------- | ------------------------------------------------------- |
| Namespace | `urn:nfi:iot:swu:1.0` |
| Package identity | Local file name, without folder or embedded version |
| Freshness signal | Publication timestamp and optional superseded timestamp |
## Package metadata
```xml theme={null}
```
`signature`, `published`, `created`, `url`, and `bytes` are required. Signature algorithm and trust keys are manufacturer policy, not inferred from the download server.
The protocol supports querying one package, listing available packages, subscribing/unsubscribing, receiving package-change notifications, and inspecting current subscriptions. Uploading a package and the on-device installation procedure are deliberately implementation-specific.
## Safe client flow
1. Discover the update service with XMPP service discovery.
2. Query package metadata or subscribe by stable file name.
3. Compare `published` with the last verified installation record.
4. Apply randomized delay/backoff before download.
5. Stream to a staging area while enforcing the advertised byte limit.
6. Verify the complete package signature against a pinned manufacturer trust policy.
7. Back up state and check disk, power, hardware, and dependency prerequisites.
8. Install atomically or into an inactive slot.
9. Health-check the new version and roll back on failure.
10. Persist the publication timestamp and outcome for audit.
Never install a package merely because it came from an authenticated broker or HTTPS origin. The package signature and trusted manufacturer key are the authenticity boundary.
## Distribution at fleet scale
Brokers can mirror packages in a hierarchy and notify their own connected devices. This prevents a release to millions of devices from becoming a coordinated load spike against one manufacturer endpoint. Clients still need jitter, bounded concurrency, resume support, and a staged rollout policy.
## Version policy
Subscriptions use a stable file name, so do not encode the software version in that name. Use the broker publication timestamp for protocol ordering and keep semantic version/build compatibility inside signed package metadata. Define downgrade and rollback authorization separately from normal upgrade policy.
# Units and conversion
Source: https://docs.neuro-tech.io/iot/units
Represent measurable quantities and convert compatible base, derived, and compound units
The unit model makes sensor values readable by people and convertible by software, including linear, non-linear, derived, and compound units.
| Item | Value |
| ---------------- | --------------------------------------------------------------------- |
| Namespace | `urn:nfi:iot:u:1.0` |
| Definition model | Unit categories with one reference unit and zero or more alternatives |
## Model
A **unit category** groups compatible units representing the same measurable quantity. It has exactly one reference unit—normally an SI unit or a unit with a derivation to SI.
A regular **unit** defines reversible Reverse Polish Notation (RPN) operations that map its value to the category reference unit. A **compound unit** is a numeric factor multiplied by unit factors raised to integer exponents. Units without conversion operations are equivalent to their category reference unit.
```mermaid theme={null}
flowchart LR
V[Input value + unit] --> P[Apply input prefix]
P --> R[Convert to category reference]
R --> T[Convert reference to target]
T --> O[Choose output prefix and precision]
```
## Conversion algorithm
1. Look up both units and verify that their reduced dimensions/categories are compatible.
2. Apply any source prefix before evaluating unit operations.
3. Push the source value on the stack and evaluate its RPN operations top-to-bottom to reach the reference unit.
4. Evaluate the target operations in reverse, using the inverse of each operation, to leave the reference unit.
5. Apply a suitable target prefix and rounding policy.
The operation set includes constants and reversible arithmetic such as number, π, add, subtract, multiply, divide, power, logarithm, and negation. An implementation must reject an invalid stack program, a non-invertible conversion, or incompatible dimensions.
## Compound units
Reduce each factor recursively into a numeric multiplier and base-unit exponent map. Compatible compound units have the same normalized exponent map.
```text theme={null}
N = kg·m·s⁻²
Pa = N·m⁻² = kg·m⁻¹·s⁻²
```
Do not compare display strings to test compatibility. Normalize definitions and dimensions instead.
## Sensor implementation rules
* Send a stable unit symbol with every quantity field for which magnitude depends on a unit.
* Preserve significant digits and quality metadata during conversion.
* Keep raw readings when a converted value will be used for audit or billing.
* Accept an unknown unit as a value you can display or store, but do not invent a conversion.
* Reject incompatible control inputs before changing device state.
# MCP permissions
Source: https://docs.neuro-tech.io/mcp/authentication-and-authorization
Reference for OAuth scopes, Neuron privileges, and roles
Use the [quickstart](/mcp/quickstart) first. This page explains the permission model when you need to configure or debug access.
## The three parts
| Part | Purpose |
| --------------- | --------------------------------------------------- |
| OAuth client | Identifies the application connecting to the Neuron |
| User or account | Signs in and authorizes the client |
| Neuron role | Grants the operations that account may authorize |
Creating a client does not grant it access. The authorizing account must have a role containing the requested privileges.
## Scope-to-privilege mapping
Neuron prefixes an OAuth scope with `OAUTH.Scope.` and replaces colons with periods:
```text theme={null}
MCP:Files:Resources:Read
→ OAUTH.Scope.MCP.Files.Resources.Read
```
Built-in scope roots are:
```text theme={null}
MCP:Files
MCP:EventLog
MCP:InternetContent
MCP:XMPP
```
Prefer specific leaf scopes. Granting `OAUTH.Scope.MCP.Files` can authorize the current and future operations below that root; it is not equivalent to read-only access.
## OAuth discovery
Clients discover the OAuth configuration from the Neuron:
```text theme={null}
https:///.well-known/oauth-authorization-server
https:///.well-known/oauth-protected-resource
```
Use the endpoints and methods advertised by those documents. Current Neuron deployments can differ in enabled registration and authentication methods.
## Credential handling
* Let the MCP client complete OAuth and store its credentials.
* Never put access tokens in URLs, prompts, documentation, or source control.
* Give each automated client its own identity and role.
* Separate read, write, and destructive permissions.
* Disable the client or account when access should end.
Bearer-token configuration is useful for diagnostics or non-interactive deployments, but it should not replace an available OAuth login flow.
# Build an MCP server package
Source: https://docs.neuro-tech.io/mcp/build-a-server
Add an OAuth-protected MCP tool to a Neuron with public NuGet packages
This guide extends the [Neuron package quickstart](/neuron-development/quickstart) with one read-only MCP tool. It does not require the Neuron, Neuro-Ledger, or IoTBroker source repositories.
## 1. Add the MCP packages
From the class-library project created in the package quickstart:
```bash theme={null}
dotnet add package Waher.Networking.HTTP.Mcp --version 1.1.0
dotnet add package Waher.Networking.HTTP.OAuth --version 1.0.1
```
Keep the existing `Waher.IoTGateway` reference. Match all package versions to the Neuron you will test against before deployment.
## 2. Add the server and module
```csharp theme={null}
using System;
using System.Threading.Tasks;
using Waher.IoTGateway;
using Waher.Networking.HTTP.JsonRpc;
using Waher.Networking.HTTP.Mcp;
using Waher.Networking.HTTP.Mcp.Model.Attributes;
using Waher.Networking.HTTP.OAuth;
using Waher.Networking.HTTP.OAuth.MetaData;
using Waher.Networking.Sniffers;
using Waher.Runtime.Inventory;
[OAuthResourceName("Example MCP Server")]
[McpScopeRoot("MCP:Example")]
public sealed class ExampleMcpServer : HttpMcpServerResource
{
private const string ReadPrivilege =
"OAUTH.Scope.MCP.Example.Tools.Read";
public ExampleMcpServer(string resourceName, ISnifferSet? sniffers)
: base(
resourceName,
"Example",
"Example",
"1.0.0",
"Example Neuron MCP tools.",
GetDefaultIcons(),
null,
"Use these tools only for approved example data.",
sniffers)
{
}
[McpServerTool(
"Read Value",
"Reads one value without changing state.",
"",
false, // can modify
false, // can destroy
true, // idempotent
false // open-world access
)]
[RequiredPrivilege(ReadPrivilege)]
public Task ReadValue(
[McpStringParameter("Key", "Value key.", 1, 128)] string key)
{
return Task.FromResult(key);
}
}
[Singleton]
public sealed class ExampleMcpModule : IModule
{
private ExampleMcpServer? server;
public Task Start()
{
if (Gateway.HttpServer is null)
throw new InvalidOperationException("The Neuron HTTP server is unavailable.");
this.server = new ExampleMcpServer("/MCP/Example", null);
Gateway.HttpServer.Register(this.server);
return Task.CompletedTask;
}
public Task Stop()
{
if (this.server != null && Gateway.HttpServer != null)
Gateway.HttpServer.Unregister(this.server);
this.server = null;
return Task.CompletedTask;
}
}
```
The example targets `netstandard2.1` and has been compiled with `Waher.IoTGateway` 3.10.2, MCP 1.1.0, and OAuth 1.0.1.
## 3. Build and package
```bash theme={null}
dotnet build --configuration Release
```
Add the output assembly to the same module manifest format used in the [package quickstart](/neuron-development/quickstart), then build and install the package.
## 4. Grant and test access
Create a role containing:
```text theme={null}
OAUTH.Scope.MCP.Example.Tools.Read
```
Connect Codex to:
```text theme={null}
https:///MCP/Example
```
Request the scope `MCP:Example:Tools:Read`, then call **Read Value**. Confirm that removing the privilege causes the tool call to be rejected.
## Before adding a write tool
* Give every operation its own privilege leaf.
* Describe the real side effect in the title and description.
* Set modification, destruction, idempotency, and open-world annotations accurately.
* Bound every input and validate it again in the method.
* Log the actor, target, and outcome without logging secrets.
* Test allowed, denied, invalid, repeated, and partial-failure calls.
# Enable MCP access
Source: https://docs.neuro-tech.io/mcp/connect-a-client
Operator setup for an MCP client
This page is for the person administering the Neuron. A client cannot complete OAuth setup unless the Neuron provides a client registration path and an account with the required permissions.
## 1. Select one endpoint
Start with a single endpoint and read-only access. For example:
```text theme={null}
https://neuron.example.com/MCP/Files
```
Do not use `/MCP`; the Neuron exposes separate MCP servers.
## 2. Create a role
In **Administration → Users and Roles → Roles**, create a role for the client. A read-only Files role can contain:
```text theme={null}
OAUTH.Scope.MCP.Files.Resources.List
OAUTH.Scope.MCP.Files.Resources.Read
OAUTH.Scope.MCP.Files.Tools.Search
```
Assign the role to the account that will authorize the client. Registration alone does not grant access.
## 3. Choose client registration
Use one of these approaches:
* **Pre-provisioned static client ID:** use a deployment-specific client registration that has already been configured and tested with Codex, including its redirect URI.
* **Dynamic client registration (DCR):** enable it only if your deployment has been configured and tested for it. The client registers during `codex mcp login`.
Do not ask developers to obtain and paste access tokens as the normal setup. Their MCP client should perform the OAuth flow and store its own credentials.
Codex cannot sign in unless the Neuron provides a registered OAuth client or dynamic client registration. If neither is available, the operator must configure OAuth before the developer continues.
## 4. Give the developer a connection profile
Provide these values together:
```text theme={null}
Neuron: https://neuron.example.com
MCP endpoint: https://neuron.example.com/MCP/Files
Client ID: # omit only when DCR is enabled
Scopes: MCP:Files:Resources:List,MCP:Files:Resources:Read,MCP:Files:Tools:Search
Sign-in:
```
Never include a client secret, access token, or refresh token in the profile.
## 5. Test the granted permissions
After the developer signs in:
1. Confirm a read-only request succeeds.
2. Confirm an ungranted write request is rejected.
3. Check the Neuron event log for the request.
See [MCP permissions](/mcp/authentication-and-authorization) when you need to design a different permission set.
# Connect to a local Neuron
Source: https://docs.neuro-tech.io/mcp/local-neuron
Prepare a Neuron you administer for local MCP development
“Local” means you administer the Neuron. Codex may run on the same machine or elsewhere; the OAuth and permission model is the same.
## 1. Confirm the Neuron is ready
Complete [installation](/operations/install) and [first run](/operations/first-run). Then confirm the target endpoint responds over HTTPS:
```bash theme={null}
curl -i https:///MCP/Files
```
An authentication response is expected. A `404` means the endpoint or module is unavailable.
## 2. Add a read-only role
Open **Administration → Users and Roles → Roles** and create a role with:
```text theme={null}
OAUTH.Scope.MCP.Files.Resources.List
OAUTH.Scope.MCP.Files.Resources.Read
OAUTH.Scope.MCP.Files.Tools.Search
```
Assign it to the account you will use during OAuth login.
## 3. Make client registration available
Choose one path:
* Use a static OAuth client already provisioned for Codex by the distribution or deployment tooling.
* Enable and test dynamic client registration for your deployment.
The Neuron's OAuth metadata must be reachable at:
```bash theme={null}
curl --fail https:///.well-known/oauth-authorization-server
```
If your installation does not provide either client-registration path, MCP login is not ready. The current public administration surface does not provide a universal manual-client workflow, and generating a token by hand is not the missing setup step.
## 4. Connect Codex
Continue with [Connect Codex](/mcp/quickstart), using your actual host and registration method.
Begin with `/MCP/Files` and read-only scopes. Add write or destructive privileges only after read access works and you have tested which resources the account can reach.
# MCP on a Neuron
Source: https://docs.neuro-tech.io/mcp/overview
Connect an AI development client to capabilities exposed by a Neuron
Model Context Protocol (MCP) lets an AI client call tools and read resources exposed by a Neuron. You connect to one capability at a time and sign in through the Neuron's OAuth service.
MCP servers differ by deployment. Ask the Neuron operator for the endpoint, OAuth client settings, required role, and list of enabled tools.
Add a Neuron endpoint, sign in, and make a first read-only request.
## Common MCP endpoints
| Endpoint | Use it to |
| --------------- | ---------------------------------------------------------------------- |
| `/MCP/Files` | List, read, search, and—when permitted—change files in account storage |
| `/MCP/EventLog` | Search or write operational events |
| `/MCP/Content` | Fetch Internet content through the Neuron |
| `/MCP/XMPP` | Work with messages and contacts over XMPP |
There is no documented combined `/MCP` endpoint. A package can add other endpoints, so use the exact URL supplied by the Neuron operator.
## What you need
You do **not** need the Neuron source code. You need:
* a reachable Neuron URL;
* an MCP endpoint;
* an OAuth client ID, or confirmation that dynamic client registration is enabled;
* an account or sign-in flow with the required role.
For a Neuron running on your machine, you configure access yourself. For another Neuron, its operator provides these values and grants access.
## Choose another tool when
The listed servers do not create or install Neuron packages, author contracts, or issue tokens. Use the [package tools](/neuron-development/quickstart), [LegalLab](/contracts/legallab-quickstart), or [Agent API](/contracts/agent-api-quickstart) for those tasks.
Configure access when you administer the Neuron.
Connect using values supplied by its operator.
Choose an endpoint and review its permissions.
Add MCP tools from a C# package.
# Connect Codex
Source: https://docs.neuro-tech.io/mcp/quickstart
Add a Neuron MCP endpoint and sign in with OAuth
This example connects Codex to the read-only parts of a Neuron's file server. You do not need to retrieve an OAuth token yourself.
## Before you start
Install a current Codex client and obtain this connection profile from the Neuron operator:
```text theme={null}
Endpoint: https://neuron.example.com/MCP/Files
Client ID: , or confirmation that DCR is enabled
Scopes:
```
If the Neuron is yours, follow [Connect to a local Neuron](/mcp/local-neuron) first.
Installing a Neuron does not by itself guarantee a Codex-compatible OAuth client-registration path. The operator must configure either a static client for Codex or working DCR before this login can succeed.
## 1. Add the endpoint
When you have a pre-registered client ID:
```bash theme={null}
codex mcp add neuron-files --url https://neuron.example.com/MCP/Files --oauth-client-id YOUR_CLIENT_ID
```
When the operator has confirmed automatic OAuth client registration (CIMD or DCR):
```bash theme={null}
codex mcp add neuron-files --url https://neuron.example.com/MCP/Files
```
## 2. Sign in
Start the OAuth flow:
```bash theme={null}
codex mcp login neuron-files
```
Codex opens the Neuron's sign-in and authorization flow. Complete it in the browser. Codex stores the resulting credentials; do not copy an access token into the command or configuration file. When both CIMD and DCR are available, Codex chooses automatically. Use `codex mcp login --help` before forcing a registration method for an operator-specific setup.
See the [official Codex MCP reference](https://developers.openai.com/codex/mcp) for the current client flags, OAuth selection rules, and configuration-file format.
## 3. Verify the connection
```bash theme={null}
codex mcp list
codex
```
Inside Codex, run `/mcp`. Confirm `neuron-files` is connected, then ask:
```text theme={null}
Use neuron-files to list the files I can access. Do not modify anything.
```
If login, discovery, or permissions fail, use [Troubleshoot MCP](/mcp/troubleshooting).
## Use a different server
Replace the endpoint and OAuth connection profile with those supplied for `/MCP/EventLog`, `/MCP/Content`, or `/MCP/XMPP`. Do not assume these servers are deployed or that the same role grants access to every one.
# Connect to another Neuron
Source: https://docs.neuro-tech.io/mcp/remote-neuron
Use MCP without administering the remote deployment
You do not need access to the Neuron, Neuro-Ledger, or IoTBroker source repositories. You do need the remote Neuron's operator to enable access.
## Request a connection profile
Ask for all of these values together:
```text theme={null}
Neuron URL
Exact MCP endpoint
OAuth client ID, or confirmation that DCR is enabled
Allowed OAuth scopes
Sign-in instructions
Test request that should succeed
```
An endpoint URL by itself is insufficient. An OAuth client without an assigned role is also insufficient.
## Connect
Use the supplied values in [Connect Codex](/mcp/quickstart). Codex performs OAuth login in the browser; the operator should not send you a shared bearer token.
## When access is missing
The operator must complete [Enable MCP access](/mcp/connect-a-client). There is no client-side command that can create Neuron privileges or bypass a disabled client-registration flow.
## Keep environments separate
Use a different Codex MCP entry for each Neuron and capability:
```text theme={null}
neuron-dev-files
neuron-test-files
neuron-test-events
```
This makes the target visible before a tool call and reduces accidental changes in the wrong environment.
# Event Log MCP server
Source: https://docs.neuro-tech.io/mcp/servers/event-log
Search structured events and let authorized agents record operational activity
The Event Log server at `/MCP/EventLog` connects agents to Neuron's structured operational log.
## Logging tools
There is one tool for each event severity:
```text theme={null}
Log Debug Event
Log Informational Event
Log Notice Event
Log Warning Event
Log Error Event
Log Critical Error Event
Log Alert Event
Log Emergency Event
```
Each has its own privilege below `OAUTH.Scope.MCP.EventLog.Tools.Log`.
Common fields are:
| Field | Purpose |
| --------- | --------------------------------------------- |
| Message | Human-readable body |
| Object | Object affected by the event |
| Actor | Subject that caused it |
| Level | Minor, Medium, or Major operational impact |
| Event ID | Stable identifier for reports and correlation |
| Facility | External component or subsystem |
| Module | Component inside the facility |
| Meta Data | Structured key/value tags |
Alert and Emergency events are propagated to operators immediately. Do not use them for normal retryable failures.
## Search for Events
The search tool accepts pagination plus optional UTC time range and event-field filters. Results indicate whether more events exist and the offset for the next page. Grant it with:
```text theme={null}
OAUTH.Scope.MCP.EventLog.Tools.Search
```
## Find Sensitive Information prompt
The built-in prompt helps an agent inspect logged events for potentially sensitive information. It requires:
```text theme={null}
OAUTH.Scope.MCP.EventLog.Prompts.FindSensitiveInfo
```
The prompt assists review; it does not replace retention, redaction, or access-control policy.
## Logging guidance for agents
* Use a stable event ID for the same class of event.
* Put identifiers in structured fields, not prose.
* Do not log access tokens, passwords, private keys, full identity documents, or contract secrets.
* Record the actor that authorized an external action.
* Log a denied destructive request as a security-relevant event without copying the secret input.
# File Storage MCP server
Source: https://docs.neuro-tech.io/mcp/servers/file-storage
Manage private, persistent, account-specific agent files
The File Storage server at `/MCP/Files` gives each authenticated account a separate persistent file area. It publishes files as MCP resources and supplies tools for controlled mutation.
## Resources
The server supports resource listing and reading when the caller has:
```text theme={null}
OAUTH.Scope.MCP.Files.Resources.List
OAUTH.Scope.MCP.Files.Resources.Read
```
Resource URIs are local to the account and must not be shared as public download URLs.
## Tools
| Tool | Behavior | Privilege suffix |
| ------------------ | ------------------------------------------- | ---------------- |
| Create Text File | Create or replace UTF-8 text with BOM | `.Tools.Create` |
| Create Binary File | Create or replace decoded binary content | `.Tools.Create` |
| Append Text File | Append text; create if absent | `.Tools.Append` |
| Append Binary File | Append bytes; create if absent | `.Tools.Append` |
| Update Text File | Replace an existing text file | `.Tools.Update` |
| Update Binary File | Replace an existing binary file | `.Tools.Update` |
| Delete File | Delete an existing file | `.Tools.Delete` |
| Search | Match file names with `*` and `?` wildcards | `.Tools.Search` |
| Edit | Apply an edit to an existing file | `.Tools.Edit` |
## Path and type rules
* Local names cannot start with a path separator.
* `..` path traversal is rejected.
* File extensions must agree with the Internet content type.
* Executable files must not be stored.
* Folders can organize an account's area, but cannot escape it.
## Safe role examples
Read-only retrieval:
```text theme={null}
OAUTH.Scope.MCP.Files.Resources.List
OAUTH.Scope.MCP.Files.Resources.Read
OAUTH.Scope.MCP.Files.Tools.Search
```
Document authoring without deletion:
```text theme={null}
OAUTH.Scope.MCP.Files.Resources.List
OAUTH.Scope.MCP.Files.Resources.Read
OAUTH.Scope.MCP.Files.Tools.Create
OAUTH.Scope.MCP.Files.Tools.Update
OAUTH.Scope.MCP.Files.Tools.Edit
```
Mark sensitive content through the tool's sensitivity input where available, and never use the file area as a secret vault.
# Internet Content MCP server
Source: https://docs.neuro-tech.io/mcp/servers/internet-content
Retrieve and modify Internet resources through a controlled Neuron egress point
The Internet Content server at `/MCP/Content` lets an MCP client make outbound requests using Neuron's content decoders. When the Neuron has a client certificate, requests can use it for mTLS.
## Tools
| Tool | Modifies | Destructive | Idempotent | Privilege suffix |
| ------ | -------- | ----------- | ---------- | ---------------- |
| Get | No | No | Yes | `.Tools.Get` |
| Post | Yes | Yes | No | `.Tools.Post` |
| Put | Yes | Yes | Yes | `.Tools.Put` |
| Delete | Yes | Yes | No | `.Tools.Delete` |
| Query | No | No | Yes | `.Tools.Query` |
The full privilege prefix is `OAUTH.Scope.MCP.InternetContent`.
## Common parameters
* `URI`: absolute target URI.
* `Accept`: expected response media type; defaults to `*/*`.
* `Accept-Language`: preferred human language.
* `Timeout`: 1–60,000 ms; defaults to 30,000 ms.
* `AdditionalHeaders`: optional string-valued request headers.
* `Payload`: object encoded for POST, PUT, or QUERY.
The result contains the decoded content together with its Internet content type and source URI.
## Egress policy
This server has open-world access. Granting `Get` allows an agent to reach addresses visible from the Neuron, which may include private infrastructure.
Production controls should:
* allow secure schemes such as HTTPS and reject insecure HTTP;
* block loopback, link-local, cloud metadata, and private address ranges unless explicitly needed;
* resolve DNS again at connection time to reduce rebinding risk;
* restrict target hosts and ports;
* remove credentials from redirects to another origin;
* cap body sizes and timeouts;
* log target, actor, method, status, and policy decision.
Do not grant write methods to an agent that only summarizes web content.
# MCP servers
Source: https://docs.neuro-tech.io/mcp/servers/overview
Compare file, event-log, Internet-content, and XMPP tools exposed by a Neuron
Each MCP server exposes one capability and has its own OAuth scope and Neuron privileges. Connect only the server your AI application needs.
Enabled servers and tool counts differ by deployment. Use the MCP discovery response from your Neuron instead of assuming every item below is available.
| Server | Endpoint | Tools | Resources | Prompt |
| ---------------- | --------------- | ----: | ---------------------------- | -------------------------- |
| Event Log | `/MCP/EventLog` | 9 | No | Find Sensitive Information |
| Internet Content | `/MCP/Content` | 5 | No | — |
| File Storage | `/MCP/Files` | 9 | Account files | — |
| XMPP | `/MCP/XMPP` | 10 | Roster contacts and messages | — |
## Select the smallest server
Connect an agent only to the server it needs. There is no joined `/MCP` endpoint.
## Tool annotations
Neuron declares MCP safety hints on each tool:
* whether it can modify the environment;
* whether it can destroy data;
* whether repeated calls are idempotent;
* whether it accesses the open world.
These annotations help a client plan tool calls; they do not grant access. Authentication and Neuron privileges determine what the account can do.
## Resource isolation
File and XMPP resources are account-specific and require authentication. A resource URI obtained by one agent must not be treated as a shareable public URL.
## Extension model
Packages can register additional `HttpMcpServerResource` implementations. An extension should publish its own OAuth resource name, scope root, narrow privilege leaves, and accurate safety annotations. See [Build an MCP server](/mcp/build-a-server).
# XMPP MCP server
Source: https://docs.neuro-tech.io/mcp/servers/xmpp
Give an agent consent-based messaging on the federated XMPP network
The XMPP server at `/MCP/XMPP` associates each MCP client with an XMPP account. It publishes roster contacts and received messages as account-specific resources.
## Resources
* `xmpp:` resources represent contacts in the account's roster.
* message resources represent messages received by the agent.
* listing and reading require `.Resources.List` and `.Resources.Read` privileges.
The in-memory client connection is cached and removed after prolonged inactivity. An agent that must retain a message should read and store it rather than treating the MCP resource list as permanent archival storage.
## Tools
| Area | Tools | Privilege branch |
| -------- | ------------------------------------------------------------- | ------------------- |
| Presence | Request subscription, accept, decline, request unsubscription | `.Tools.Presence.*` |
| Roster | Add, update, remove roster item | `.Tools.Roster.*` |
| Messages | Send chat message, get message, pop message | `.Tools.Message.*` |
The full root is `OAUTH.Scope.MCP.XMPP`.
## Consent-first messaging flow
Ask the contact for a presence subscription before sending messages or information queries.
The remote party can accept or decline. Presence state and roster resources show the relationship.
Send plain text plus optional Markdown/HTML representations only after the relationship permits it.
Read or pop incoming messages. Persist business-relevant messages in an appropriate application store.
## Credentials
If no XMPP account is associated with the MCP client, the server can elicit XMPP credentials. Prefer an operator-created, role-scoped account for production. Dynamic OAuth registrations create an XMPP account but leave normal XMPP communication disabled until an operator enables it.
## Safety
* Do not let an agent auto-accept arbitrary presence requests.
* Maintain an allowlist for automated outbound destinations.
* Treat message bodies as untrusted input that can contain prompt injection.
* Keep the identity of the human or workflow that authorized a message in the audit log.
* Rate-limit retries and presence operations.
# Troubleshoot MCP
Source: https://docs.neuro-tech.io/mcp/troubleshooting
Fix common Codex, OAuth, endpoint, and permission failures
## `404 Not Found`
Use one of the exact built-in paths:
```text theme={null}
/MCP/Files
/MCP/EventLog
/MCP/Content
/MCP/XMPP
```
There is no combined `/MCP` endpoint. Also check URL casing, reverse-proxy path rewriting, and whether the module providing the endpoint started successfully.
## `codex mcp login` cannot discover OAuth
Open both metadata documents directly:
```bash theme={null}
curl --fail https://neuron.example.com/.well-known/oauth-authorization-server
curl --fail https://neuron.example.com/.well-known/oauth-protected-resource
```
If either fails, fix the Neuron, TLS certificate, DNS, or proxy before changing Codex configuration.
## Client registration fails
Dynamic registration is optional. Ask the operator whether DCR is enabled and tested. Otherwise remove the MCP entry and add it again with a supplied client ID:
```bash theme={null}
codex mcp remove neuron-files
codex mcp add neuron-files --url https://neuron.example.com/MCP/Files --oauth-client-id YOUR_CLIENT_ID
```
## Login succeeds but requests return `403`
The account lacks one or more requested privileges. Compare each requested scope with its role privilege:
```text theme={null}
MCP:Files:Resources:Read
OAUTH.Scope.MCP.Files.Resources.Read
```
After the role changes, log in again so Codex obtains a token with the new scope.
## No tools or resources appear
* Confirm Codex is connected to the intended specialized endpoint.
* Run `codex mcp list` and inspect `/mcp` inside Codex.
* Check that the requested leaf scopes include the operation you expect.
* Check Neuron startup and event logs for module errors.
## Bearer token works only in one terminal
`--bearer-token-env-var` stores the environment variable's **name**, not its value. Define that variable in every process that launches Codex. Do not put the token itself in `config.toml`.
## Information to collect
Record the endpoint, UTC time, client ID, requested scopes, HTTP status, JSON-RPC error, Neuron version, and event ID. Remove access tokens, refresh tokens, authorization codes, cookies, client secrets, and passwords.
# Audit trails
Source: https://docs.neuro-tech.io/neuro-ledger/audit-trail
Distinguish ledger history, domain history, and operational events
“Audit log” can refer to three different records on a Neuron. Use the one that answers your question.
| Record | Answers | Access |
| --------------------- | ----------------------------------------------------- | ------------------------------------------ |
| Domain history | What happened to this contract, token, or identity? | Agent API or domain client |
| Operational event log | What did this Neuron process, warn about, or reject? | Administration UI or Event Log MCP |
| Neuro-Ledger blocks | Which persisted changes were signed and synchronized? | Ledger administration and authorized peers |
The operational event log is not proof that an object was committed to the ledger. A ledger block is not a substitute for presenting the current signed contract or token history to an application user.
## Application audit checklist
1. Store the domain object ID returned by the Neuron.
2. Store the operation time and the authenticated actor in your application log.
3. Retrieve the object or its history from the owning API when evidence is needed.
4. Correlate failures with Neuron event IDs.
5. Ask the operator for ledger verification only when the assurance requirement calls for it.
Never copy protected contract parameters, credentials, or private ledger content into an unrestricted application log.
# Developer access to ledger-backed data
Source: https://docs.neuro-tech.io/neuro-ledger/developer-access
Choose a supported interface without relying on private implementation source
There is currently no general public endpoint for applications to append arbitrary records directly to Neuro-Ledger. Use the domain interface that owns the record.
| You want to | Use |
| ------------------------------------------ | ---------------------------------------------------------------------------- |
| Create or read contracts | [Agent API contract endpoints](/neuron-api/api-reference/contracts/overview) |
| Work with Neuro-Features | [Token flow](/neuron-api/guides/tokens-flow) |
| Develop a Neuron module | [Package quickstart](/neuron-development/quickstart) |
| Search operational events | [Event Log MCP server](/mcp/servers/event-log) |
| Inspect ledger health or synchronize peers | Neuron administration UI |
## Package developers
Using Neuron persistence from a package does not by itself guarantee a public, replicated audit record. Treat ledger inclusion as an explicit deployment capability that must be agreed with the Neuron operator and documented for the object type.
Do not take a dependency on internal ledger assemblies, storage files, `/NL/*` implementation endpoints, or repository layout. Those are not the supported public contract for a package.
## Application developers
Keep the identifier returned by the domain API—for example, a contract ID or token ID. Use that same API to retrieve the current object and its exposed history. This remains stable even when ledger storage and peer topology change.
## MCP developers
The Event Log MCP server returns operational events, not raw Neuro-Ledger blocks. A future ledger-specific MCP server would need its own documented resources, tools, scopes, and privacy boundary; do not assume one exists today.
# How Neuro-Ledger works
Source: https://docs.neuro-tech.io/neuro-ledger/how-it-works
A conceptual view of entries, blocks, signatures, and synchronization
## 1. A Neuron changes a persisted object
The application performs a normal operation, such as creating or updating an object. Ledger participation is determined by the installed service and object configuration; it is not requested by adding a special field to an API call.
## 2. The ledger records the change
New, updated, deleted, and cleared records can become ledger entries. Entries retain the information needed to identify the operation and verify its recorded representation.
## 3. Entries are collected into blocks
The Neuron groups entries by collection and closes blocks according to its configured collection interval and size threshold. The node signs the resulting block and publishes its reference.
## 4. Authorized peers synchronize
Approved contacts exchange block references over XMPP. A peer retrieves a block only when access policy permits it, then verifies the block before accepting its contents.
## 5. History can be checked
Operators can inspect block statistics, collections, signatures, and synchronization results. Applications normally inspect the higher-level contract, token, or object history exposed by their supported API.
## Protect private ledger data
“Distributed” does not mean “public.” A deployment can require a data-protection agreement and authorization before another node can retrieve blocks. Whether a specific record is shared depends on the deployment and collection policy.
# Neuro-Ledger
Source: https://docs.neuro-tech.io/neuro-ledger/overview
Learn what the ledger records and which interface to use for application access
Neuro-Ledger is the Neuron's distributed audit and persistence layer. It records selected object changes in signed blocks and synchronizes them with authorized peers.
It is not a public cryptocurrency chain, a smart-contract virtual machine, or an API that every application writes to directly.
## Where it fits
```mermaid theme={null}
flowchart LR
A[Application] --> I[Neuron interface]
I --> O[Contracts, tokens, identities, and other objects]
O --> L[Neuro-Ledger]
L --> P[Authorized ledger peers]
```
Most developers use the [Agent API](/neuron-api/introduction), [contracts](/contracts/overview), or package APIs. The Neuron decides which resulting records belong in the ledger.
## What applications gain
* Important changes can be traced over time.
* Blocks and references are signed and can be checked for integrity.
* Synchronization is between identified, authorized peers rather than an anonymous global network.
* Access controls can protect ledger content that should not be public.
## Use a Neuron interface
The supported developer surface is the installed Neuron and its documented APIs. The Neuro-Ledger implementation repository is not required for application development and is not currently part of the public integration surface.
Follow a record from persistence to a synchronized block.
See which interface to use for each task.
# API basics
Source: https://docs.neuro-tech.io/neuron-api/api-basics
Use the correct Agent API base URL, HTTP method, request body, and response handling
## Base URL
All API requests are made to your Neuron's domain:
```text theme={null}
https://{host}
```
Where `{host}` is the Neuron domain issued to you by your operator. There is no shared central URL — each Neuron deployment has its own domain.
All endpoints are prefixed with `/Agent/`. For example:
```text theme={null}
https://{host}/Agent/Account/Login
```
## HTTP methods
The current Neuron Agent API specification uses `POST` for most operations. `GET /Agent/Account/DomainInfo` is the documented exception. Operations with request bodies use JSON.
## Request structure
Operations inherit JWT bearer authentication unless their OpenAPI entry explicitly overrides security. For bearer-authenticated calls, send:
```text theme={null}
Authorization: Bearer {token}
Content-Type: application/json
```
Several account and session operations explicitly override the global bearer requirement. Login and account creation use HMAC values in the request body. Other anonymous operations have their own request requirements. Check the generated operation before deciding that a request is anonymous.
When a documented `POST` operation has no parameters, its request is still an empty JSON object:
```json theme={null}
{}
```
## Response structure
Documented successful response bodies use JSON when a schema is present. The shape varies per endpoint—see the individual [API reference](/neuron-api/api-reference/overview) pages.
The OpenAPI document does not define a platform-wide error body or complete non-success response set. See [Error handling](/neuron-api/error-handling) before writing response parsing or retry logic.
## Federated network
Some operations explicitly document federated behavior, including retrieving or signing contracts created on another Neuron. Do not assume every object or operation supports federation. See [Federation](/neuron-api/federation) for details.
# Create account
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/create-account
/test-api/openapi.yaml post /Agent/Account/Create
Create a Neuron account and receive an initial JWT
## Overview
Creates a new agent account and logs the user in. The account behaves like a
regular XMPP account. New accounts are disabled until their email address is
verified. Phone verification is optional if a phone number is provided.
## Authentication
This endpoint requires an API key and secret. Sign the request with HMAC-SHA256
using the API secret as the key.
Signature message:
```
userName:host:eMail:password:apiKey:nonce
```
## Notes
* Protect your API key and secret. They should only be used from secure back-end
services.
* Each API key has a limit on how many accounts it can create.
* If you cannot protect secrets (for example, in a browser), use CreateWebForm.
# Create Web Form
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/create-web-form
/test-api/openapi.yaml post /Agent/Account/CreateWebForm
Creates an agent account on the server manually (and logs in to it).
## Overview
Creates an agent account on the server manually (and logs in to it). This account can be used when logging in, using the Agent API, but also to connect to the Neuron using any of the available XMPP bindings available. The account that is created, is considered a regular XMPP account on the broker.
When first created, the account is in a disabled state. You need to validate the e-mail address provided in the request first (and the phone number, if providing a phone number), before the account can be enabled. An e-mail with a verification code will be sent to the e-mail address provided in the request. If providing a phone number, an SMS will be sent to the phone number.
Note: To use this function, you need to configure the Neuron for use with Google Recaptcha, to protect against malicious account creation. This can be done using the same configuration as is used by the Feedback page. This also means, that when POSTing the request to the resource, it will be posted as a web form, not JSON or XML, as with most of the the other resources defined in this API. You also provide a redirection URL to redirect the user, upon successful creation of an account.
Security Notice: To create accounts on the Neuron, an API Key is required. This resource requires an API Key to be generated on the Neuron, with the Owner set to Agent API. If no such key is available, or if the account limit configured in the key is reached, no more accounts can be generated using this resource until such a key is created or its limit increased. You can disable account creation using this resource, by simply removing any such API Key configured, or setting the limit at the number of accounts already created using the API Key. The following table shows if such a key is available, and if accounts can be created using this resource.
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Domain Info
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/domain-info
/test-api/openapi.yaml get /Agent/Account/DomainInfo
Gets human-readable information about the domain of the server.
## Overview
Gets human-readable information about the domain of the server. This resource is accessed using HTTP GET, so there is no payload sent to resource. The request can be made anonymously. No authentication is required. This resource is typically called in the beginning of an on-boarding process, where the user is given a choice to select service provider (i.e. domain).
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Info
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/info
/test-api/openapi.yaml post /Agent/Account/Info
Gets information about the currently logged in account.
## Overview
Gets information about the currently logged in account. The account does not need to be enabled for this resource to return information about the account. The information will be somewhat restricted if the account is not enabled.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Accounts and onboarding
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/overview
Agent API operations for account creation, verification, recovery, information, and transfer
This page lists 9 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Existing account](/neuron-api/quickstart)
* [Trusted-backend creation](/neuron-api/guides/creating-an-account)
* [Browser onboarding](/neuron-api/guides/browser-based-signup)
## Operations
| Operation | Purpose | Authentication |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ----------------------------- |
| [`POST /Agent/Account/Create`](/neuron-api/api-reference/accounts-and-onboarding/create-account) | Create account | Operation-specific; no bearer |
| [`POST /Agent/Account/CreateWebForm`](/neuron-api/api-reference/accounts-and-onboarding/create-web-form) | Create Web Form | Operation-specific; no bearer |
| [`GET /Agent/Account/DomainInfo`](/neuron-api/api-reference/accounts-and-onboarding/domain-info) | Domain Info | Operation-specific; no bearer |
| [`POST /Agent/Account/Info`](/neuron-api/api-reference/accounts-and-onboarding/info) | Info | JWT bearer |
| [`POST /Agent/Account/Recover`](/neuron-api/api-reference/accounts-and-onboarding/recover) | Recover | Operation-specific; no bearer |
| [`POST /Agent/Account/ResendVerificationCodes`](/neuron-api/api-reference/accounts-and-onboarding/resend-verification-codes) | Resend Verification Codes | Operation-specific; no bearer |
| [`POST /Agent/Account/Transfer`](/neuron-api/api-reference/accounts-and-onboarding/transfer) | Transfer | JWT bearer |
| [`POST /Agent/Account/VerifyEMail`](/neuron-api/api-reference/accounts-and-onboarding/verify-email) | Verify email | Operation-specific; no bearer |
| [`POST /Agent/Account/VerifyPhoneNr`](/neuron-api/api-reference/accounts-and-onboarding/verify-phone-number) | Verify Phone Nr | Operation-specific; no bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Make the first authenticated Agent API call](/neuron-api/quickstart) | `POST /Agent/Account/Info` |
| [Onboard a verified Neuro identity](/build/verified-identity/overview) | `POST /Agent/Account/Create`
`POST /Agent/Account/VerifyEMail` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Accounts and Legal Identities](/platform/accounts-and-identities)
* [Authentication and sessions](/neuron-api/api-reference/authentication-and-sessions/overview)
# Recover
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/recover
/test-api/openapi.yaml post /Agent/Account/Recover
Start account recovery without revealing account existence
## Overview
Starts a recovery process when a user has lost access. The server may send a
recovery email, request peer approval, or notify the operator depending on the
account status.
This endpoint can be called without an existing session.
## Authentication
No authentication required.
# Resend Verification Codes
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/resend-verification-codes
/test-api/openapi.yaml post /Agent/Account/ResendVerificationCodes
If, during onboarding, the verification codes do not arrive, or are lost, the client can request the codes to be resent.
## Overview
If, during onboarding, the verification codes do not arrive, or are lost, the client can request the codes to be resent. To do this, the client needs to provide the token generated during account creation, as well as the eMail or phone number whose code they wish to resend.
Security Notice: It is not possible to resend codes for accounts, numbers or e-mail addresses that have been verified. You can only resend codes for accounts still pending verification. This includes partially verified accounts. If the phone number has been verified, but the e-mail address has not, or vice versa, you can resend the code for the unverified part, but not for the verified part. Attempting to resend codes that have been verified, will be flagged, and repetetive calls to resend codes for verified accounts, numbers or addresses may result in the temporary and then permanent blocking of the endpoint making the call.
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Transfer
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/transfer
/test-api/openapi.yaml post /Agent/Account/Transfer
Allows the client to transfer an account created using the Agent API to another application, such as Neuro-Access.
## Overview
Allows the client to transfer an account created using the Agent API to another application, such as Neuro-Access. If the account has an associated current Legal ID, the ID will also be transferred to the new application. To transfer an account, without Legal ID, the Key ID, and Key Signatures can be omitted. If transferring an account with any associated Legal ID, and its corresponding private key, the Key ID and Key Signatures must be provided.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Verify email
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/verify-email
/test-api/openapi.yaml post /Agent/Account/VerifyEMail
Enable an account by verifying the email address
## Overview
New accounts are disabled until the email address is verified. Call this
endpoint with the code sent to the user.
## Authentication
No authentication required.
# Verify Phone Nr
Source: https://docs.neuro-tech.io/neuron-api/api-reference/accounts-and-onboarding/verify-phone-number
/test-api/openapi.yaml post /Agent/Account/VerifyPhoneNr
Verifies a phone number corresponding to an account that is being created.
## Overview
Verifies a phone number corresponding to an account that is being created. When creating an account using /Account/Create, the account is at first disabled. This means, it cannot be used actively in the API. To enable an account, you need to verify the e-mail address provided when creating the account. If providing a phone number, you need to verify the phone number as well. If not providing a phone number you can skip this step. The account creation call will send an e-mail with a code to the e-mail address, as well as an SMS to the phone number, if such is provided. The code sent to the phone number needs to be provided in a call to this resource, together with the phone number
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Authenticate Jwt
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/authenticate-jwt
/test-api/openapi.yaml post /Agent/Account/AuthenticateJwt
Allows a service to authenticate a JWT token issued by the broker.
## Overview
Allows a service to authenticate a JWT token issued by the broker. This resource does not require authenticated access. Any service that receives a JWT token issued by the broker can request the broker to validate the token, and to return parsed information available in the token.
## Authentication
No bearer token is required. Pass the JWT to validate in the request body.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Session Token
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/get-session-token
/test-api/openapi.yaml post /Agent/Account/GetSessionToken
Allows the client to get session information about a newly created account, created using a web form, without having to provide user credentials again.
## Overview
Allows the client to get session information about a newly created account, created using a web form, without having to provide user credentials again.
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Login
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/login
/test-api/openapi.yaml post /Agent/Account/Login
Exchange credentials for a short-lived JWT
## Overview
Authenticates a user and returns a JWT. This method is intended for
programmatic clients and is an alternative to browser-based login flows.
## Authentication
Sign the request using HMAC-SHA256 with the account password as the key.
Signature message:
```
userName:host:nonce
```
# Logout
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/logout
/test-api/openapi.yaml post /Agent/Account/Logout
Invalidate the current JWT session
## Overview
Logs out the current session and invalidates the JWT.
## Authentication
Requires a valid JWT bearer token.
# Authentication and sessions
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/overview
Agent API operations for login, JWT validation, refresh, logout, and browser-session handoff
This page lists 10 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Direct login quickstart](/neuron-api/quickstart)
* [Compare login flows](/neuron-api/guides/login-flows)
## Operations
| Operation | Purpose | Authentication |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ----------------------------- |
| [`POST /Agent/Account/AuthenticateJwt`](/neuron-api/api-reference/authentication-and-sessions/authenticate-jwt) | Authenticate Jwt | Operation-specific; no bearer |
| [`POST /Agent/Account/GetSessionToken`](/neuron-api/api-reference/authentication-and-sessions/get-session-token) | Get Session Token | Operation-specific; no bearer |
| [`POST /Agent/Account/Login`](/neuron-api/api-reference/authentication-and-sessions/login) | Login | Operation-specific; no bearer |
| [`POST /Agent/Account/Logout`](/neuron-api/api-reference/authentication-and-sessions/logout) | Logout | JWT bearer |
| [`POST /Agent/Account/PrepareRemoteQuickLogin`](/neuron-api/api-reference/authentication-and-sessions/prepare-remote-quick-login) | Prepare Remote Quick Login | JWT bearer |
| [`POST /Agent/Account/QuickLogin`](/neuron-api/api-reference/authentication-and-sessions/quick-login) | Quick Login | Operation-specific; no bearer |
| [`POST /Agent/Account/Refresh`](/neuron-api/api-reference/authentication-and-sessions/refresh) | Refresh | JWT bearer |
| [`POST /Agent/Account/RemoteQuickLogin`](/neuron-api/api-reference/authentication-and-sessions/remote-quick-login) | Remote Quick Login | JWT bearer |
| [`POST /Agent/Account/RemoteReferences`](/neuron-api/api-reference/authentication-and-sessions/remote-references) | Remote References | JWT bearer |
| [`POST /Agent/Account/WwwLogin`](/neuron-api/api-reference/authentication-and-sessions/www-login) | Www Login | Operation-specific; no bearer |
## Related guides
| Guide | Operations from this resource |
| --------------------------------------------------------------------- | ----------------------------- |
| [Make the first authenticated Agent API call](/neuron-api/quickstart) | `POST /Agent/Account/Login` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Authentication formulas](/neuron-api/authentication)
* [Accounts and onboarding](/neuron-api/api-reference/accounts-and-onboarding/overview)
# Prepare Remote Quick Login
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/prepare-remote-quick-login
/test-api/openapi.yaml post /Agent/Account/PrepareRemoteQuickLogin
Allows the client to prepare a remote Neuron for a quick login attempt made by the client, currently logged in via the Agent API.
Note: This request must be made to Neuron to which the client is connected.
## Overview
Allows the client to prepare a remote Neuron for a quick login attempt made by the client, currently logged in via the Agent API.
Note: This request must be made to Neuron to which the client is connected.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Quick Login
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/quick-login
/test-api/openapi.yaml post /Agent/Account/QuickLogin
Allows the client to authenticate itself with the API using a Quick-Login.
## Overview
Allows the client to authenticate itself with the API using a Quick-Login. performed in the current HTTP Session. This method is an alternative to the Login and WwwLogin resources.
Note: To be able to access the current session, cookies must be enabled.
Note 2: Community Login is demonstrated in the link above, as it uses Quick-Login in session mode. API documentation for Quick-Login can be found here: QuickLogin API Documentation. You need to have the Community Package installed for the Community Login to be available.
Note 3: It is assumed the Agent API account resides on the same broker. The Agent API is an HTTP REST API for using an XMPP account on an XMPP broker. Once you have made a Quick-Login in a broker, you can use the RemoteQuickLogin resource to perform session logins on other brokers using the QuickLogin on the current broker, providing the JWT token obtained from the current broker.
If authentication succeeds, a JSON Web Token (or JWT) is returned to the client. This token can be used as a Bearer token in subsequent calls to the API. It needs to be refreshed before it expires.
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Refresh
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/refresh
/test-api/openapi.yaml post /Agent/Account/Refresh
Refresh a JWT without logging in again
## Overview
Use this endpoint to obtain a new JWT before the current one expires. If refresh
fails or the token is expired, log in again.
## Authentication
Requires a valid JWT bearer token.
# Remote Quick Login
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/remote-quick-login
/test-api/openapi.yaml post /Agent/Account/RemoteQuickLogin
Allows the client to trigger a Quick Login procedure on a remote Neuron, without having to scan a QR code, and if successful, logging in on the machine using a given Legal Identity.
Note: The call to the remote neuron does not require a login or an Agent API connection.
Note 2: A Legal ID can be used to login on multiple machines.
## Overview
Allows the client to trigger a Quick Login procedure on a remote Neuron, without having to scan a QR code, and if successful, logging in on the machine using a given Legal Identity.
Note: The call to the remote neuron does not require a login or an Agent API connection.
Note 2: A Legal ID can be used to login on multiple machines. If administrative access is granted to the corresponding Legal Identity, an administrative login will also be performed, if the login is successful.
Note 3: Only session logins (i.e. admin logins and quick-logins) can be made using this resource. No new JWT token will be generated, as the Agent API can only be connected to the broker associated with the account the agent is using.
Note 4: You can prepare the the remote quick login procedure by calling the /Account/PrepareRemoteQuickLogin resource to get the Legal ID associated with the current account.
Note 5: This method of initiating the Quick-Login does not require the client to scan a QR code. Instead, the request to sign the login is sent automatically to the client when the /Account/RemoteQuickLogin resource is called.
If authentication succeeds, a quick-login is performed automatically in the current session, and if there is an administrative account associated with the digital identity, such a login is also performed in the current session.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Remote References
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/remote-references
/test-api/openapi.yaml post /Agent/Account/RemoteReferences
Allows the client to get a list of references to remote neurons the user can quick-login to using /Account/RemoteQuickLogin.
Note: The list may not be complete.
## Overview
Allows the client to get a list of references to remote neurons the user can quick-login to using /Account/RemoteQuickLogin.
Note: The list may not be complete. Each time a Legal Identity is added or removed as a reference on an Neuron, an incremental message is sent ot the Neuron hosting the associated account. If the list is not complete, just remove and add the reference to the Legal ID again on the remote broker, to update the list.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Www Login
Source: https://docs.neuro-tech.io/neuron-api/api-reference/authentication-and-sessions/www-login
/test-api/openapi.yaml post /Agent/Account/WwwLogin
Allows the client to authenticate itself with the API, using the WWW-Authenticate Header available in the HTTP protocol.
If authentication succeeds, a JSON Web Token (or JWT) is returned to the client.
## Overview
Allows the client to authenticate itself with the API, using the WWW-Authenticate Header available in the HTTP protocol.
If authentication succeeds, a JSON Web Token (or JWT) is returned to the client. This token can be used as a Bearer token in subsequent calls to the API. It needs to be refreshed before it expires.
Security Notice: Some WWW-Authentication mechanism send the password in clear text. While encryption is required, password is still unpacked by the remote endpoint, which may be a security consideration. Use the Login or QuickLogin resources to avoid this. The Javascript library uses the these resources instead of the WwwLogin alternative. But if a client is unable to generate cryptographic signatures as required by the specification, traditional WWW-Authentication mechanisms are also available.
## Authentication
No authentication required.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Authorize Access To Contract
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/authorize-access-to-contract
/test-api/openapi.yaml post /Agent/Legal/AuthorizeAccessToContract
Allows the client to (pre-)authorize access to (or remove authorization to access) one of its Smart Contracts (or one of the Smart Contracts for which the client is part) to a remote party.
## Overview
Allows the client to (pre-)authorize access to (or remove authorization to access) one of its Smart Contracts (or one of the Smart Contracts for which the client is part) to a remote party. When (if) the remote party requests access to the the Smart Contract, the broker will return it automatically, if already authorized. If not authorized, a petition to access the Smart Contract will be sent to the clients of the part of the contract for manual approval.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Create Contract
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/create-contract
/test-api/openapi.yaml post /Agent/Legal/CreateContract
Allows the client to create a new smart contract, based on an existing (and approved) contract template.
## Overview
Allows the client to create a new smart contract, based on an existing (and approved) contract template. The request must be signed using one of the keys created by the client.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Contract
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/get-contract
/test-api/openapi.yaml post /Agent/Legal/GetContract
Allows the client to get a Smart Contract.
## Overview
Allows the client to get a Smart Contract. If the Contract belongs to someone else, and the client is not authorized access to the Contract, an error will be returned.
Note: Neurons are federated. You can get contracts created on other neurons through this API on the neuron you have your account on. Federated means that the neurons interconnect to share authorized information, when requested, and permitted.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Created Contracts
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/get-created-contracts
/test-api/openapi.yaml post /Agent/Legal/GetCreatedContracts
Gets smart contracts the account has created.
## Overview
Gets smart contracts the account has created.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Signed Contracts
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/get-signed-contracts
/test-api/openapi.yaml post /Agent/Legal/GetSignedContracts
Gets smart contracts the account has signed.
## Overview
Gets smart contracts the account has signed.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Contracts
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/overview
Agent API operations for templates, contract instances, access, proposals, and signatures
This page lists 9 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Build an agreement](/build/agreements/overview)
* [Use contract API operations](/contracts/agent-api-quickstart)
## Operations
| Operation | Purpose | Authentication |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- |
| [`POST /Agent/Legal/AuthorizeAccessToContract`](/neuron-api/api-reference/contracts/authorize-access-to-contract) | Authorize Access To Contract | JWT bearer |
| [`POST /Agent/Legal/CreateContract`](/neuron-api/api-reference/contracts/create-contract) | Create Contract | JWT bearer |
| [`POST /Agent/Legal/GetContract`](/neuron-api/api-reference/contracts/get-contract) | Get Contract | JWT bearer |
| [`POST /Agent/Legal/GetCreatedContracts`](/neuron-api/api-reference/contracts/get-created-contracts) | Get Created Contracts | JWT bearer |
| [`POST /Agent/Legal/GetSignedContracts`](/neuron-api/api-reference/contracts/get-signed-contracts) | Get Signed Contracts | JWT bearer |
| [`POST /Agent/Legal/ProposeTemplate`](/neuron-api/api-reference/contracts/propose-contract-template) | Propose Template | JWT bearer |
| [`POST /Agent/Legal/SendProposal`](/neuron-api/api-reference/contracts/send-proposal) | Send Proposal | JWT bearer |
| [`POST /Agent/Legal/SignContract`](/neuron-api/api-reference/contracts/sign-contract) | Sign Contract | JWT bearer |
| [`POST /Agent/Legal/SignData`](/neuron-api/api-reference/contracts/sign-data) | Sign Data | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Build a tokenized product passport](/build/tokenized-assets/overview) | `POST /Agent/Legal/CreateContract` |
| [Create an agreement between two verified parties](/build/agreements/overview) | `POST /Agent/Legal/CreateContract`
`POST /Agent/Legal/SendProposal`
`POST /Agent/Legal/SignContract`
`POST /Agent/Legal/GetContract` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Smart contracts](/platform/smart-contracts)
* [Contract lifecycle](/neuron-api/guides/contracts-flow)
# Propose Template
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/propose-contract-template
/test-api/openapi.yaml post /Agent/Legal/ProposeTemplate
Allows the client to propose a new smart contract template.
## Overview
Allows the client to propose a new smart contract template. The smart contract template is an XML document that conforms to the smart contract schema. You can design smart contracts using the LegalLab application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send Proposal
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/send-proposal
/test-api/openapi.yaml post /Agent/Legal/SendProposal
Sends a contract proposal to another XMPP Client (in the federated network) to sign a specific contract under a specific role.
## Overview
Sends a contract proposal to another XMPP Client (in the federated network) to sign a specific contract under a specific role. The proposal message can also contain a plain text message to the recipient.
Note: This function calls the AgentAPI.Xmpp.SendXmlMessage(To,Xml,Subject,Language,Id) function, which calls the corresponding Agent API web service.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Sign Contract
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/sign-contract
/test-api/openapi.yaml post /Agent/Legal/SignContract
Allows the client to sign a smart contract.
Note: Neurons are federated.
## Overview
Allows the client to sign a smart contract.
Note: Neurons are federated. You can sign contracts created on other neurons through this API on the neuron you have your account on. Federated means that the neurons interconnect to share authorized information, when requested, and permitted.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Sign Data
Source: https://docs.neuro-tech.io/neuron-api/api-reference/contracts/sign-data
/test-api/openapi.yaml post /Agent/Legal/SignData
Allows the client to sign binary data.
## Overview
Allows the client to sign binary data.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Create Key
Source: https://docs.neuro-tech.io/neuron-api/api-reference/cryptography/create-key
/test-api/openapi.yaml post /Agent/Crypto/CreateKey
Allows the client to create a cryptographic key on the server, and protect it with a password.
## Overview
Allows the client to create a cryptographic key on the server, and protect it with a password. The key will be stored encrypted on the server, protected with the key password. The creation of a key will require the user to provide the account password again.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Algorithms
Source: https://docs.neuro-tech.io/neuron-api/api-reference/cryptography/get-algorithms
/test-api/openapi.yaml post /Agent/Crypto/GetAlgorithms
Allows the client to retrieve a list of available cryptographic algorithms on the server.
## Overview
Allows the client to retrieve a list of available cryptographic algorithms on the server. These algorithms can be used to create keys. These keys are necessary in order to apply for legal identities, which are then used to sign smart contracts.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Public Key
Source: https://docs.neuro-tech.io/neuron-api/api-reference/cryptography/get-public-key
/test-api/openapi.yaml post /Agent/Crypto/GetPublicKey
Allows the client to get the current server public key, or the public key of one of its own cryptographic keys.
## Overview
Allows the client to get the current server public key, or the public key of one of its own cryptographic keys. The client can use this key to validate signatures server in relation to legal identities, smart contracts, tokens, etc.
Note: If a Key ID is provided, information about one of the keys of the client account is returned. If not Key ID is provided, information about the the public server key is returned.
Note 2: If no Key ID is provided, resource requires no authentication. If a Key ID is provided, a Bearer token identifying the client account must be provided.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Cryptography
Source: https://docs.neuro-tech.io/neuron-api/api-reference/cryptography/overview
Agent API operations for algorithm discovery, key creation, and public-key retrieval
This page lists 3 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Create a cryptographic key](/neuron-api/guides/creating-cryptographic-keys)
## Operations
| Operation | Purpose | Authentication |
| ------------------------------------------------------------------------------------------- | -------------- | -------------- |
| [`POST /Agent/Crypto/CreateKey`](/neuron-api/api-reference/cryptography/create-key) | Create Key | JWT bearer |
| [`POST /Agent/Crypto/GetAlgorithms`](/neuron-api/api-reference/cryptography/get-algorithms) | Get Algorithms | JWT bearer |
| [`POST /Agent/Crypto/GetPublicKey`](/neuron-api/api-reference/cryptography/get-public-key) | Get Public Key | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------------------- | ------------------------------ |
| [Onboard a verified Neuro identity](/build/verified-identity/overview) | `POST /Agent/Crypto/CreateKey` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Keys and signatures](/platform/keys-and-signatures)
* [Digital signatures](/build/digital-signatures/overview)
# Add Id Attachment
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/add-id-attachment
/test-api/openapi.yaml post /Agent/Legal/AddIdAttachment
Allows the client to add an attachment to a Legal Identity application.
## Overview
Allows the client to add an attachment to a Legal Identity application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Apply Id
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/apply-for-id
/test-api/openapi.yaml post /Agent/Legal/ApplyId
Allows the client to apply for a new Legal Identity on the server.
## Overview
Allows the client to apply for a new Legal Identity on the server. The application must be signed using one of the keys created by the client.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Authorize Access To Id
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/authorize-access-to-id
/test-api/openapi.yaml post /Agent/Legal/AuthorizeAccessToId
Allows the client to (pre-)authorize access to (or remove authorization to access) one of its Legal Identities to a remote party.
## Overview
Allows the client to (pre-)authorize access to (or remove authorization to access) one of its Legal Identities to a remote party. When (if) the remote party requests the ID, the broker will return it automatically, if already authorized. If not authorized, a petition to access the identity will be sent to the client for manual approval (or rejection).
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Application Attributes
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/get-application-attributes
/test-api/openapi.yaml post /Agent/Legal/GetApplicationAttributes
Allows the client to get important attributes necessary to perform a correct ID Application.
## Overview
Allows the client to get important attributes necessary to perform a correct ID Application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Identities
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/get-identities
/test-api/openapi.yaml post /Agent/Legal/GetIdentities
Gets the account's legal identities.
## Overview
Gets the account's legal identities.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Identity
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/get-identity
/test-api/openapi.yaml post /Agent/Legal/GetIdentity
Allows the client to get an Identity.
## Overview
Allows the client to get an Identity. If the Identity belongs to someone else, and the client is not authorized access to the Identity, an error will be returned.
Note: Neurons are federated. You can get identities created on other neurons through this API on the neuron you have your account on. Federated means that the neurons interconnect to share authorized information, when requested, and permitted.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Service Providers For Id Review
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/get-service-providers-for-id-review
/test-api/openapi.yaml post /Agent/Legal/GetServiceProvidersForIdReview
Allows the client to retrieve a list of available service providers that can be used to review a recent ID application.
## Overview
Allows the client to retrieve a list of available service providers that can be used to review a recent ID application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Legal identities
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/overview
Agent API operations for identity applications, evidence, review, retrieval, and petitions
This page lists 13 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Build with verified identity](/build/verified-identity/overview)
* [Follow the identity lifecycle](/neuron-api/guides/legal-identity-flow)
## Operations
| Operation | Purpose | Authentication |
| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | -------------- |
| [`POST /Agent/Legal/AddIdAttachment`](/neuron-api/api-reference/legal-identities/add-id-attachment) | Add Id Attachment | JWT bearer |
| [`POST /Agent/Legal/ApplyId`](/neuron-api/api-reference/legal-identities/apply-for-id) | Apply Id | JWT bearer |
| [`POST /Agent/Legal/AuthorizeAccessToId`](/neuron-api/api-reference/legal-identities/authorize-access-to-id) | Authorize Access To Id | JWT bearer |
| [`POST /Agent/Legal/GetApplicationAttributes`](/neuron-api/api-reference/legal-identities/get-application-attributes) | Get Application Attributes | JWT bearer |
| [`POST /Agent/Legal/GetIdentities`](/neuron-api/api-reference/legal-identities/get-identities) | Get Identities | JWT bearer |
| [`POST /Agent/Legal/GetIdentity`](/neuron-api/api-reference/legal-identities/get-identity) | Get Identity | JWT bearer |
| [`POST /Agent/Legal/GetServiceProvidersForIdReview`](/neuron-api/api-reference/legal-identities/get-service-providers-for-id-review) | Get Service Providers For Id Review | JWT bearer |
| [`POST /Agent/Legal/PetitionId`](/neuron-api/api-reference/legal-identities/petition-id) | Petition Id | JWT bearer |
| [`POST /Agent/Legal/PetitionPeerReview`](/neuron-api/api-reference/legal-identities/petition-peer-review) | Petition Peer Review | JWT bearer |
| [`POST /Agent/Legal/PetitionSignature`](/neuron-api/api-reference/legal-identities/petition-signature) | Petition Signature | JWT bearer |
| [`POST /Agent/Legal/ReadyForApproval`](/neuron-api/api-reference/legal-identities/ready-for-approval) | Ready For Approval | JWT bearer |
| [`POST /Agent/Legal/SelectReviewService`](/neuron-api/api-reference/legal-identities/select-review-service) | Select Review Service | JWT bearer |
| [`POST /Agent/Legal/ValidatePNr`](/neuron-api/api-reference/legal-identities/validate-pnr) | Validate PNr | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Onboard a verified Neuro identity](/build/verified-identity/overview) | `POST /Agent/Legal/GetApplicationAttributes`
`POST /Agent/Legal/ApplyId`
`POST /Agent/Legal/AddIdAttachment`
`POST /Agent/Legal/ReadyForApproval`
`POST /Agent/Legal/GetIdentity` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Accounts and Legal Identities](/platform/accounts-and-identities)
* [Cryptography](/neuron-api/api-reference/cryptography/overview)
# Petition Id
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/petition-id
/test-api/openapi.yaml post /Agent/Legal/PetitionId
Allows the client to petition the owner of a Legal Identity, for information about the identity.
## Overview
Allows the client to petition the owner of a Legal Identity, for information about the identity.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Petition Peer Review
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/petition-peer-review
/test-api/openapi.yaml post /Agent/Legal/PetitionPeerReview
Allows the client to petition a peer to review an ID application.
## Overview
Allows the client to petition a peer to review an ID application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Petition Signature
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/petition-signature
/test-api/openapi.yaml post /Agent/Legal/PetitionSignature
Allows the client to petition the owner of a Legal Identity for a digital signature on some digital content.
## Overview
Allows the client to petition the owner of a Legal Identity for a digital signature on some digital content.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Ready For Approval
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/ready-for-approval
/test-api/openapi.yaml post /Agent/Legal/ReadyForApproval
When an ID application is ready (all attachments have been signed and uploaded), the client can call this resource to flag the application as ready for approval.
## Overview
When an ID application is ready (all attachments have been signed and uploaded), the client can call this resource to flag the application as ready for approval. This will execute any automated onboarding procedures to analyze the application, and, if passing them, will take the identity to the approved state. They can also take the application to the rejected state, in case they find the information invalid.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Select Review Service
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/select-review-service
/test-api/openapi.yaml post /Agent/Legal/SelectReviewService
Allows the client to select an internal peer review service, for reviewing a recent identity application.
## Overview
Allows the client to select an internal peer review service, for reviewing a recent identity application.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Validate PNr
Source: https://docs.neuro-tech.io/neuron-api/api-reference/legal-identities/validate-pnr
/test-api/openapi.yaml post /Agent/Legal/ValidatePNr
Allows the client to validate a personal number before using it to apply for a Legal Identity.
## Overview
Allows the client to validate a personal number before using it to apply for a Legal Identity.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Clear Messages
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/clear-messages
/test-api/openapi.yaml post /Agent/Xmpp/ClearMessages
Clears any offline messages available for the account from the server.
## Overview
Clears any offline messages available for the account from the server.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Roster
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/get-roster
/test-api/openapi.yaml post /Agent/Xmpp/GetRoster
Gets the account's roster.
## Overview
Gets the account's roster.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Roster Item
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/get-roster-item
/test-api/openapi.yaml post /Agent/Xmpp/GetRosterItem
Gets information about a specific roster item for the account.
## Overview
Gets information about a specific roster item for the account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Information Query
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/information-query
/test-api/openapi.yaml post /Agent/Xmpp/InformationQuery
Sends an Information Query (iq) to an entity on the XMPP network, given its Full JID.
## Overview
Sends an Information Query (iq) to an entity on the XMPP network, given its Full JID. For connected entities, you need to have an presence subscription to that entity, approved by the entity, to get the Full JID. You get the Full JID using the Presence Probe resource.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Messaging
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/overview
Agent API operations for XMPP messages, presence, roster, retrieval, and browser events
This page lists 16 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Send and receive messages](/neuron-api/guides/messaging)
* [Receive browser events](/neuron-api/guides/webhooks)
## Operations
| Operation | Purpose | Authentication |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- |
| [`POST /Agent/Xmpp/ClearMessages`](/neuron-api/api-reference/messaging/clear-messages) | Clear Messages | JWT bearer |
| [`POST /Agent/Xmpp/GetRoster`](/neuron-api/api-reference/messaging/get-roster) | Get Roster | JWT bearer |
| [`POST /Agent/Xmpp/GetRosterItem`](/neuron-api/api-reference/messaging/get-roster-item) | Get Roster Item | JWT bearer |
| [`POST /Agent/Xmpp/InformationQuery`](/neuron-api/api-reference/messaging/information-query) | Information Query | JWT bearer |
| [`POST /Agent/Xmpp/PopMessages`](/neuron-api/api-reference/messaging/pop-messages) | Pop Messages | JWT bearer |
| [`POST /Agent/Xmpp/PresenceProbe`](/neuron-api/api-reference/messaging/presence-probe) | Presence Probe | JWT bearer |
| [`POST /Agent/Xmpp/RegisterEventHandler`](/neuron-api/api-reference/messaging/register-event-handler) | Register Event Handler | JWT bearer |
| [`POST /Agent/Xmpp/RemoveRosterItem`](/neuron-api/api-reference/messaging/remove-roster-item) | Remove Roster Item | JWT bearer |
| [`POST /Agent/Xmpp/SendFormattedMessage`](/neuron-api/api-reference/messaging/send-formatted-message) | Send formatted message | JWT bearer |
| [`POST /Agent/Xmpp/SendPresenceSubscription`](/neuron-api/api-reference/messaging/send-presence-subscription) | Send Presence Subscription | JWT bearer |
| [`POST /Agent/Xmpp/SendPresenceUnsubscription`](/neuron-api/api-reference/messaging/send-presence-unsubscription) | Send Presence Unsubscription | JWT bearer |
| [`POST /Agent/Xmpp/SendSubscriptionAccepted`](/neuron-api/api-reference/messaging/send-subscription-accepted) | Send Subscription Accepted | JWT bearer |
| [`POST /Agent/Xmpp/SendSubscriptionDeclined`](/neuron-api/api-reference/messaging/send-subscription-declined) | Send Subscription Declined | JWT bearer |
| [`POST /Agent/Xmpp/SendTextMessage`](/neuron-api/api-reference/messaging/send-text-message) | Send text message | JWT bearer |
| [`POST /Agent/Xmpp/SendXmlMessage`](/neuron-api/api-reference/messaging/send-xml-message) | Send Xml Message | JWT bearer |
| [`POST /Agent/Xmpp/SetRosterItem`](/neuron-api/api-reference/messaging/set-roster-item) | Set Roster Item | JWT bearer |
## Related guides
No task guide currently links to these operations. Use the operation pages as reference material, not as an inferred multi-step procedure.
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Federation](/neuron-api/federation)
* [Events and asynchronous state](/neuron-api/events-and-asynchronous-state)
# Pop Messages
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/pop-messages
/test-api/openapi.yaml post /Agent/Xmpp/PopMessages
Gets messages for the account from the server.
## Overview
Gets messages for the account from the server.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Presence Probe
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/presence-probe
/test-api/openapi.yaml post /Agent/Xmpp/PresenceProbe
Gets the latest presence issued by a contact in your roster who has approved your presence subscription request.
Note: The result to the presence probe request will give you the latest Full JID published by the contact.
## Overview
Gets the latest presence issued by a contact in your roster who has approved your presence subscription request.
Note: The result to the presence probe request will give you the latest Full JID published by the contact. This Full JID can be used to make directed information queries to the contact.
Security Note: You are only allowed to send a presence probe to contacts that have approved a presence subscription from you.
Note 2: If you request the presence of an entity to which you do not have a presence subscription, one will be sent automatically. If you want to send custom XML in the presence subscription request, you should call SendPresenceSubscription.md first.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Register Event Handler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/register-event-handler
/test-api/openapi.yaml post /Agent/Xmpp/RegisterEventHandler
Registers (or unregisters) an event handler on the client, that gets called when the account receives an XMPP message of a given type.
## Overview
Registers (or unregisters) an event handler on the client, that gets called when the account receives an XMPP message of a given type. When such a message is received that matches a registered event handler, the message is pushed as a client event to the client, instead of being stored on the broker, as an offline message.
Note: For client events to be received on the client, you need to include the /Events.js javascript file on the page. This javascript file will register the current tab with the server, and enable it to receive asynchronous events from the server. If you are hosting the page on one server, and use the Agent API and Events API from another server, you need to include a meta header on the page, information the /Events.js javascript file where it will register itself to receive client events. To use this neuron, add the following to the HTML header of your page:
You also need to inform the AgentAPI that you want to use another host, than the server used to host the page. You do this by making a call to AgentAPI.IO.SetHost(Host,Secure) as follows:
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Remove Roster Item
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/remove-roster-item
/test-api/openapi.yaml post /Agent/Xmpp/RemoveRosterItem
Removes a specific roster item for the account.
## Overview
Removes a specific roster item for the account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send formatted message
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-formatted-message
/test-api/openapi.yaml post /Agent/Xmpp/SendFormattedMessage
Send a Markdown message with text and HTML representations
## Overview
Send a formatted chat message. Provide Markdown in `message` and the server
creates plain text and HTML representations for recipients to choose from.
## Authentication
Requires a valid JWT bearer token.
# Send Presence Subscription
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-presence-subscription
/test-api/openapi.yaml post /Agent/Xmpp/SendPresenceSubscription
Allows the client to send a presence subscription from its account to an XMPP recipient.
## Overview
Allows the client to send a presence subscription from its account to an XMPP recipient. If the account to which the client is logged in has an approved Legal ID associated with it, this ID will be included in the request, to allow the recipient to know who has made the request.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send Presence Unsubscription
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-presence-unsubscription
/test-api/openapi.yaml post /Agent/Xmpp/SendPresenceUnsubscription
Allows the client to send a presence unsubscription from its account to an XMPP recipient.
## Overview
Allows the client to send a presence unsubscription from its account to an XMPP recipient.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send Subscription Accepted
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-subscription-accepted
/test-api/openapi.yaml post /Agent/Xmpp/SendSubscriptionAccepted
Allows the client to accept a presence subscription made to its account.
## Overview
Allows the client to accept a presence subscription made to its account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send Subscription Declined
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-subscription-declined
/test-api/openapi.yaml post /Agent/Xmpp/SendSubscriptionDeclined
Allows the client to decline a presence subscription made to its account.
## Overview
Allows the client to decline a presence subscription made to its account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Send text message
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-text-message
/test-api/openapi.yaml post /Agent/Xmpp/SendTextMessage
Send a plain text XMPP chat message
## Overview
Send a plain text chat message from the authenticated account to an XMPP
recipient.
## Authentication
Requires a valid JWT bearer token.
# Send Xml Message
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/send-xml-message
/test-api/openapi.yaml post /Agent/Xmpp/SendXmlMessage
Allows the client to send a custom XML normal message from its account to an XMPP recipient.
## Overview
Allows the client to send a custom XML normal message from its account to an XMPP recipient.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Set Roster Item
Source: https://docs.neuro-tech.io/neuron-api/api-reference/messaging/set-roster-item
/test-api/openapi.yaml post /Agent/Xmpp/SetRosterItem
Sets information about a specific roster item for the account.
## Overview
Sets information about a specific roster item for the account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Add
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/add
/test-api/openapi.yaml post /Agent/Intelligence/Add
Allows the client to add open intelligence about an endpoint.
## Overview
Allows the client to add open intelligence about an endpoint.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Check Endpoint
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/check-endpoint
/test-api/openapi.yaml post /Agent/Intelligence/CheckEndpoint
Allows the client to check open intelligence of an endpoint.
## Overview
Allows the client to check open intelligence of an endpoint.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Delete
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/delete
/test-api/openapi.yaml post /Agent/Intelligence/Delete
Allows the client to delete open intelligence about an endpoint.
## Overview
Allows the client to delete open intelligence about an endpoint. The intelligence information must have been created by the same agent, on the same domain to be able to be deleted.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/get
/test-api/openapi.yaml post /Agent/Intelligence/Get
Allows the client to get open intelligence based on input search parameters.
## Overview
Allows the client to get open intelligence based on input search parameters. You can search on endpoint, vector, protocol, classification, code or time interval. You can leave input fields empty. Only fields with non-empty values will restrict the result set in the search. Use the offset and max count arguments to implement pagination.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Open intelligence
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/overview
Agent API operations for publishing, querying, updating, deleting, and checking endpoint intelligence
This page lists 5 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Operations
| Operation | Purpose | Authentication |
| ------------------------------------------------------------------------------------------------------ | -------------- | -------------- |
| [`POST /Agent/Intelligence/Add`](/neuron-api/api-reference/open-intelligence/add) | Add | JWT bearer |
| [`POST /Agent/Intelligence/CheckEndpoint`](/neuron-api/api-reference/open-intelligence/check-endpoint) | Check Endpoint | JWT bearer |
| [`POST /Agent/Intelligence/Delete`](/neuron-api/api-reference/open-intelligence/delete) | Delete | JWT bearer |
| [`POST /Agent/Intelligence/Get`](/neuron-api/api-reference/open-intelligence/get) | Get | JWT bearer |
| [`POST /Agent/Intelligence/Update`](/neuron-api/api-reference/open-intelligence/update) | Update | JWT bearer |
## Related guides
No task guide currently links to these operations. Use the operation pages as reference material, not as an inferred multi-step procedure.
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Authorization and privileges](/neuron-api/authorization-and-privileges)
* [Requests and responses](/neuron-api/requests-and-responses)
# Update
Source: https://docs.neuro-tech.io/neuron-api/api-reference/open-intelligence/update
/test-api/openapi.yaml post /Agent/Intelligence/Update
Allows the client to update open intelligence about an endpoint.
## Overview
Allows the client to update open intelligence about an endpoint. The intelligence information must have been created by the same agent, on the same domain to be able to be updated.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Agent API playground
Source: https://docs.neuro-tech.io/neuron-api/api-reference/openapi/overview
Browse Agent API operations and send requests to a development Neuron
Use the playground to browse request and response schemas or send a request to a development Neuron. Do not enter production credentials in a shared browser or screen-sharing session.
Most operations require a JWT bearer token. Follow the [authentication guide](/neuron-api/authentication) or call [Login](/neuron-api/api-reference/authentication-and-sessions/login) first.
## Endpoint groups
* [Accounts & onboarding](/neuron-api/api-reference/accounts-and-onboarding/overview)
* [Authentication & sessions](/neuron-api/api-reference/authentication-and-sessions/overview)
* [Messaging](/neuron-api/api-reference/messaging/overview)
* [Legal identities](/neuron-api/api-reference/legal-identities/overview)
* [Contracts](/neuron-api/api-reference/contracts/overview)
* [Wallet](/neuron-api/api-reference/wallet/overview)
* [Tokens](/neuron-api/api-reference/tokens/overview)
* [State machines](/neuron-api/api-reference/state-machines/overview)
* [Storage](/neuron-api/api-reference/storage/overview)
* [Cryptography](/neuron-api/api-reference/cryptography/overview)
* [Open intelligence](/neuron-api/api-reference/open-intelligence/overview)
# Use the Agent API reference
Source: https://docs.neuro-tech.io/neuron-api/api-reference/overview
Find request methods, paths, authentication rules, fields, and response schemas
Use the generated operation pages to check an endpoint's method, path, authentication, request body, and documented success response. Start with [Authentication](/neuron-api/authentication) and [API basics](/neuron-api/api-basics) before implementing your first operation.
## Base URL
```text theme={null}
https://{host}
```
Use the Neuron domain you were issued credentials for. Replace `{host}` with your Neuron server domain in all requests.
## Authentication
Most endpoints require a JWT bearer token passed in the `Authorization` header:
```text theme={null}
Authorization: Bearer {token}
```
Obtain a token via [Login](/neuron-api/api-reference/authentication-and-sessions/login) or [Create account](/neuron-api/api-reference/accounts-and-onboarding/create-account). Some endpoints also require HMAC-signed requests — see the [Authentication guide](/neuron-api/authentication) for details.
## Browse by resource
### [Accounts and onboarding](/neuron-api/api-reference/accounts-and-onboarding/overview)
Create and manage Neuron accounts, verify email and phone, recover access, and transfer accounts to other applications.
### [Authentication and sessions](/neuron-api/api-reference/authentication-and-sessions/overview)
Log in, refresh tokens, authenticate JWTs, and manage session flows including Quick Login and WWW-Authenticate.
### [Messaging](/neuron-api/api-reference/messaging/overview)
Send text and formatted XMPP messages, manage presence subscriptions, probe contacts, and maintain your roster.
### [Legal identities](/neuron-api/api-reference/legal-identities/overview)
Apply for legal identities, attach supporting documents, request peer or service review, and petition for signatures or identity access.
### [Contracts](/neuron-api/api-reference/contracts/overview)
Create and propose smart contract templates, send proposals to counterparties, sign contracts, and manage access authorization.
### [Wallet](/neuron-api/api-reference/wallet/overview)
Query eDaler balances, process eDaler URIs, and initiate buy/sell flows through available service providers.
### [Tokens](/neuron-api/api-reference/tokens/overview)
Inspect token metadata, query token events, retrieve creation attributes, and add text or XML notes to tokens.
### [State machines](/neuron-api/api-reference/state-machines/overview)
Query the current state of a token's state machine and generate transition reports in multiple formats.
### [Storage](/neuron-api/api-reference/storage/overview)
Save and load private XML, manage encrypted vault items, search vault contents, and create shareable vault links.
### [Cryptography](/neuron-api/api-reference/cryptography/overview)
Discover available cryptographic algorithms, create signing keys, and retrieve server or account public keys.
### [Open intelligence](/neuron-api/api-reference/open-intelligence/overview)
Publish, query, update, and delete open intelligence records about endpoints, and check endpoint status.
### [OpenAPI / playground](/neuron-api/api-reference/openapi/overview)
Explore and test all endpoints interactively using the built-in OpenAPI playground.
# Create Report
Source: https://docs.neuro-tech.io/neuron-api/api-reference/state-machines/create-report
/test-api/openapi.yaml post /Agent/StateMachines/CreateReport
Creates a report relating to a state machine associated with a token.
## Overview
Creates a report relating to a state machine associated with a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Current State
Source: https://docs.neuro-tech.io/neuron-api/api-reference/state-machines/get-current-state
/test-api/openapi.yaml post /Agent/StateMachines/GetCurrentState
Gets the current state of a state machine, associated with a token.
## Overview
Gets the current state of a state machine, associated with a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# State machines
Source: https://docs.neuro-tech.io/neuron-api/api-reference/state-machines/overview
Agent API operations for current state and state-machine reports
This page lists 2 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Work with tokenized assets](/build/tokenized-assets/overview)
## Operations
| Operation | Purpose | Authentication |
| --------------------------------------------------------------------------------------------------------- | ----------------- | -------------- |
| [`POST /Agent/StateMachines/CreateReport`](/neuron-api/api-reference/state-machines/create-report) | Create Report | JWT bearer |
| [`POST /Agent/StateMachines/GetCurrentState`](/neuron-api/api-reference/state-machines/get-current-state) | Get Current State | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------------------- | ------------------------------------------- |
| [Build a tokenized product passport](/build/tokenized-assets/overview) | `POST /Agent/StateMachines/GetCurrentState` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Neuro-Features and state machines](/platform/neuro-features-and-state-machines)
* [Tokens](/neuron-api/api-reference/tokens/overview)
# Content storage availability
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/content
Confirm whether your Neuron supports binary uploads before using the documented content resource
This resource is not included in the Agent API OpenAPI document. Confirm its paths, methods, headers, visibility rules, media types, and response fields on your Neuron before using it.
The content resource stores binary files in the name of the authenticated account. Unlike most Agent endpoints, it uses normal HTTP content negotiation and supports `PUT`, multipart `POST`, `GET`, and `DELETE`.
## Resource paths
```text theme={null}
/Agent/Storage/Content
/Agent/Storage/Content/{account}/{contentId}
```
After an upload, use the returned `url` for reads, replacements, deletion, and sharing. A `contentId` can contain `/` path separators, but its final file extension must match the registered media type.
## Authentication
Uploading, replacing, and deleting require the authenticated owner. Reading depends on the stored visibility:
| Visibility | Who can retrieve the content |
| ---------- | ------------------------------------------------------ |
| `Public` | Anyone, without authentication |
| `Presence` | Roster contacts with an approved presence subscription |
| `Private` | Only the uploader |
## Upload with PUT
Send the file bytes to a chosen resource path. The `Content-Type` must be recognized by the Neuron, and the extension in `contentId` must match it.
```bash theme={null}
curl -X PUT \
"https://neuron.example/Agent/Storage/Content/alice/report.pdf" \
-H "Authorization: Bearer $NEURON_TOKEN" \
-H "Content-Type: application/pdf" \
-H "X-Visibility: Private" \
--data-binary @report.pdf
```
Omit a caller-selected ID only when using multipart `POST`; the server then derives one from the content ETag.
## Upload with multipart POST
Post `multipart/form-data` to `/Agent/Storage/Content` with these fields:
| Field | Required | Description |
| ------------ | -------- | ----------------------------------------------------- |
| `Content` | Yes | File body and its media type |
| `ContentId` | No | Requested resource name; include a matching extension |
| `Visibility` | Yes | `Public`, `Presence`, or `Private` |
```bash theme={null}
curl -X POST "https://neuron.example/Agent/Storage/Content" \
-H "Authorization: Bearer $NEURON_TOKEN" \
-F "Content=@report.pdf;type=application/pdf" \
-F "ContentId=reports/quarterly.pdf" \
-F "Visibility=Private"
```
The JavaScript Agent library exposes the same operation as:
```javascript theme={null}
const response = await AgentAPI.Storage.Upload(
contentFile,
"reports/quarterly.pdf",
"Private"
);
```
## Upload response
Both upload methods return a content reference:
```json theme={null}
{
"uploaded": "2026-08-19T10:15:00Z",
"visibility": "Private",
"etag": "\"content-etag\"",
"url": "https://neuron.example/Agent/Storage/Content/alice/reports/quarterly.pdf"
}
```
| Field | Meaning |
| ------------ | ---------------------------------------- |
| `uploaded` | UTC upload time |
| `visibility` | Effective access policy |
| `etag` | Entity tag for the stored representation |
| `url` | Canonical URL for subsequent operations |
## Retrieve, replace, or delete
* `GET {url}` returns the original bytes with their stored `Content-Type` after applying the visibility rule.
* `PUT {url}` replaces the owner's content and returns a new content reference.
* `DELETE {url}` removes the owner's content.
Use the ETag to identify versions in application state. A new upload can produce a new ETag even when the URL remains stable.
## Media-type restrictions
The server accepts only registered, decodable media types. It rejects server-executable formats including `text/markdown`, `text/x-cssx`, and `application/x-webscript`; serving those from account storage could otherwise cross the boundary into server-side execution.
To inspect the media types supported by the running Neuron, evaluate this in a privileged Script prompt:
```text theme={null}
InternetContent.CanDecodeContentTypes
```
`Public` makes the returned URL anonymously readable. Do not use it for identity attachments, contract evidence, keys, or other confidential data.
# Create Vault Link
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/create-vault-link
/test-api/openapi.yaml post /Agent/Storage/CreateVaultLink
Allows the client to create a secure link to a vault item, for distribution.
## Overview
Allows the client to create a secure link to a vault item, for distribution. The client can set the number of times the link can be used, as well as an expiration time.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Delete From Vault
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/delete-from-vault
/test-api/openapi.yaml post /Agent/Storage/DeleteFromVault
Allows the client to delete an item from its vault.
## Overview
Allows the client to delete an item from its vault. It is only possible to delete items that have been stored using the same account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get From Vault
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/get-from-vault
/test-api/openapi.yaml post /Agent/Storage/GetFromVault
Allows the client to get an item from the vault.
## Overview
Allows the client to get an item from the vault. It is only possible to retrieve items that have been stored using the same account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Load Private Xml
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/load-private-xml
/test-api/openapi.yaml post /Agent/Storage/LoadPrivateXml
Allows the client to load previously saved private XML information from the server.
## Overview
Allows the client to load previously saved private XML information from the server.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Storage
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/overview
Agent API operations for private XML and vault data
This page lists 7 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Operations
| Operation | Purpose | Authentication |
| -------------------------------------------------------------------------------------------- | ----------------- | -------------- |
| [`POST /Agent/Storage/CreateVaultLink`](/neuron-api/api-reference/storage/create-vault-link) | Create Vault Link | JWT bearer |
| [`POST /Agent/Storage/DeleteFromVault`](/neuron-api/api-reference/storage/delete-from-vault) | Delete From Vault | JWT bearer |
| [`POST /Agent/Storage/GetFromVault`](/neuron-api/api-reference/storage/get-from-vault) | Get From Vault | JWT bearer |
| [`POST /Agent/Storage/LoadPrivateXml`](/neuron-api/api-reference/storage/load-private-xml) | Load Private Xml | JWT bearer |
| [`POST /Agent/Storage/SavePrivateXml`](/neuron-api/api-reference/storage/save-private-xml) | Save Private Xml | JWT bearer |
| [`POST /Agent/Storage/SearchInVault`](/neuron-api/api-reference/storage/search-in-vault) | Search In Vault | JWT bearer |
| [`POST /Agent/Storage/StoreInVault`](/neuron-api/api-reference/storage/store-in-vault) | Store In Vault | JWT bearer |
## Related guides
No task guide currently links to these operations. Use the operation pages as reference material, not as an inferred multi-step procedure.
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Security and transport](/neuron-api/security-and-transport)
* [Content storage availability](/neuron-api/api-reference/storage/content)
# Save Private Xml
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/save-private-xml
/test-api/openapi.yaml post /Agent/Storage/SavePrivateXml
Allows the client to save private information on the server using XML.
## Overview
Allows the client to save private information on the server using XML.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Search In Vault
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/search-in-vault
/test-api/openapi.yaml post /Agent/Storage/SearchInVault
Allows the client to search for items in the vault.
## Overview
Allows the client to search for items in the vault. It is only possible to retrieve items that have been stored using the same account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Store In Vault
Source: https://docs.neuro-tech.io/neuron-api/api-reference/storage/store-in-vault
/test-api/openapi.yaml post /Agent/Storage/StoreInVault
Allows the client to store information security in the vault.
## Overview
Allows the client to store information security in the vault. The information is stored encrypted is secure storage, complying with stricty industry standards such as PCI/DSS. The resource can be used to store new information, or to update existing information. Masks can be provided to the information, so that when it is retrieved later, only the masked information is returned. In return for storing the information in the vault, an opaque identifier is returned. This identifier can be safely stored by the client, and used to retrieve the information later. This allows the client to avoid storing sensitive information locally.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Add Text Note
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/add-text-note
/test-api/openapi.yaml post /Agent/Tokens/AddTextNote
Adds a text note to a token.
## Overview
Adds a text note to a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Add Xml Note
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/add-xml-note
/test-api/openapi.yaml post /Agent/Tokens/AddXmlNote
Adds an XML note to a token.
## Overview
Adds an XML note to a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Contract Tokens
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-contract-tokens
/test-api/openapi.yaml post /Agent/Tokens/GetContractTokens
Gets a list of tokens on the Neuron created by a specific contract.
## Overview
Gets a list of tokens on the Neuron created by a specific contract.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Creation Attributes
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-creation-attributes
/test-api/openapi.yaml post /Agent/Tokens/GetCreationAttributes
Gets essential attributes needed for getting the Trust Provider to accept token creation contracts.
## Overview
Gets essential attributes needed for getting the Trust Provider to accept token creation contracts.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Description
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-description
/test-api/openapi.yaml post /Agent/Tokens/GetDescription
Creates a report relating to a state machine associated with a token.
## Overview
Creates a report relating to a state machine associated with a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Token
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-token
/test-api/openapi.yaml post /Agent/Tokens/GetToken
Gets information about a token.
## Overview
Gets information about a token.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Token Events
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-token-events
/test-api/openapi.yaml post /Agent/Tokens/GetTokenEvents
Gets a list of token events.
## Overview
Gets a list of token events.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Tokens
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/get-tokens
/test-api/openapi.yaml post /Agent/Tokens/GetTokens
Gets a list of tokens on the Neuron owned by the account.
## Overview
Gets a list of tokens on the Neuron owned by the account.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Tokens
Source: https://docs.neuro-tech.io/neuron-api/api-reference/tokens/overview
Agent API operations for inspecting Neuro-Features, creation attributes, notes, and event history
This page lists 8 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Work with tokenized assets](/build/tokenized-assets/overview)
* [Inspect token data](/neuron-api/guides/tokens-flow)
## Operations
| Operation | Purpose | Authentication |
| ------------------------------------------------------------------------------------------------------ | ----------------------- | -------------- |
| [`POST /Agent/Tokens/AddTextNote`](/neuron-api/api-reference/tokens/add-text-note) | Add Text Note | JWT bearer |
| [`POST /Agent/Tokens/AddXmlNote`](/neuron-api/api-reference/tokens/add-xml-note) | Add Xml Note | JWT bearer |
| [`POST /Agent/Tokens/GetContractTokens`](/neuron-api/api-reference/tokens/get-contract-tokens) | Get Contract Tokens | JWT bearer |
| [`POST /Agent/Tokens/GetCreationAttributes`](/neuron-api/api-reference/tokens/get-creation-attributes) | Get Creation Attributes | JWT bearer |
| [`POST /Agent/Tokens/GetDescription`](/neuron-api/api-reference/tokens/get-description) | Get Description | JWT bearer |
| [`POST /Agent/Tokens/GetToken`](/neuron-api/api-reference/tokens/get-token) | Get Token | JWT bearer |
| [`POST /Agent/Tokens/GetTokenEvents`](/neuron-api/api-reference/tokens/get-token-events) | Get Token Events | JWT bearer |
| [`POST /Agent/Tokens/GetTokens`](/neuron-api/api-reference/tokens/get-tokens) | Get Tokens | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Build a tokenized product passport](/build/tokenized-assets/overview) | `POST /Agent/Tokens/GetCreationAttributes`
`POST /Agent/Tokens/GetContractTokens`
`POST /Agent/Tokens/GetToken`
`POST /Agent/Tokens/GetTokenEvents` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Neuro-Features and state machines](/platform/neuro-features-and-state-machines)
* [Contracts](/neuron-api/api-reference/contracts/overview)
# Get Balance
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-balance
/test-api/openapi.yaml post /Agent/Wallet/GetBalance
Allows the client to retrieve information about the current state of its wallet.
## Overview
Allows the client to retrieve information about the current state of its wallet.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Payment Options For Buying Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-payment-options-for-buying-edaler
/test-api/openapi.yaml post /Agent/Wallet/GetPaymentOptionsForBuyingEDaler
Allows the client to initiate the process of getting payment options for buying eDaler.
## Overview
Allows the client to initiate the process of getting payment options for buying eDaler.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Payment Options For Selling Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-payment-options-for-selling-edaler
/test-api/openapi.yaml post /Agent/Wallet/GetPaymentOptionsForSellingEDaler
Allows the client to initiate the process of getting payment options for selling eDaler.
## Overview
Allows the client to initiate the process of getting payment options for selling eDaler.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Service Providers For Buying Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-service-providers-for-buying-edaler
/test-api/openapi.yaml post /Agent/Wallet/GetServiceProvidersForBuyingEDaler
Allows the client to retrieve a list of available service providers that can be used to buy eDaler.
## Overview
Allows the client to retrieve a list of available service providers that can be used to buy eDaler.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Service Providers For Selling Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-service-providers-for-selling-edaler
/test-api/openapi.yaml post /Agent/Wallet/GetServiceProvidersForSellingEDaler
Allows the client to retrieve a list of available service providers that can be used to sell eDaler.
## Overview
Allows the client to retrieve a list of available service providers that can be used to sell eDaler.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Get Transaction Information
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/get-transaction-information
/test-api/openapi.yaml post /Agent/Wallet/GetTransactionInformation
Allows the client to get updated transaction information from the server.
## Overview
Allows the client to get updated transaction information from the server. It also allows the client to re-register the current Tab ID (from Events.js) and function to call, in case changes are registered with the server-side transaction object. Call this function to restart event notification if you navigate between pages.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Initiate Buy Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/initiate-buy-edaler
/test-api/openapi.yaml post /Agent/Wallet/InitiateBuyEDaler
Allows the client to initiate the process of buying eDaler, using a service provider that does not use a smart contract as the basis for the transaction (i.e.
## Overview
Allows the client to initiate the process of buying eDaler, using a service provider that does not use a smart contract as the basis for the transaction (i.e. a service provider that will require the client to open a third-party page to complete the transaction).
Note: Service Providers publishing a smart contract template as the basis of operation start processing transactions when the contract has been created and signed by the client and the Trust Provider. There is no need to initiate the process by calling this resource in such cases.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Initiate Sell Edaler
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/initiate-sell-edaler
/test-api/openapi.yaml post /Agent/Wallet/InitiateSellEDaler
Allows the client to initiate the process of selling eDaler, using a service provider that does not use a smart contract as the basis for the transaction (i.e.
## Overview
Allows the client to initiate the process of selling eDaler, using a service provider that does not use a smart contract as the basis for the transaction (i.e. a service provider that will require the client to open a third-party page to complete the transaction).
Note: Service Providers publishing a smart contract template as the basis of operation start processing transactions when the contract has been created and signed by the client and the Trust Provider. There is no need to initiate the process by calling this resource in such cases.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Wallet
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/overview
Agent API operations for eDaler balances, providers, buy and sell initiation, and transaction lookup
This page lists 9 Agent API operations generated from this repository's OpenAPI document. Open an operation to check its method, path, fields, and documented success response.
The API description may not list every required privilege, error, retry rule, side effect, or event. Confirm missing behavior on the Neuron version you will use.
## Start with
* [Build a payment integration](/build/payments/overview)
* [Check payment API availability](/build/payments/neuro-pay-status)
## Operations
| Operation | Purpose | Authentication |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------- |
| [`POST /Agent/Wallet/GetBalance`](/neuron-api/api-reference/wallet/get-balance) | Get Balance | JWT bearer |
| [`POST /Agent/Wallet/GetPaymentOptionsForBuyingEDaler`](/neuron-api/api-reference/wallet/get-payment-options-for-buying-edaler) | Get Payment Options For Buying Edaler | JWT bearer |
| [`POST /Agent/Wallet/GetPaymentOptionsForSellingEDaler`](/neuron-api/api-reference/wallet/get-payment-options-for-selling-edaler) | Get Payment Options For Selling Edaler | JWT bearer |
| [`POST /Agent/Wallet/GetServiceProvidersForBuyingEDaler`](/neuron-api/api-reference/wallet/get-service-providers-for-buying-edaler) | Get Service Providers For Buying Edaler | JWT bearer |
| [`POST /Agent/Wallet/GetServiceProvidersForSellingEDaler`](/neuron-api/api-reference/wallet/get-service-providers-for-selling-edaler) | Get Service Providers For Selling Edaler | JWT bearer |
| [`POST /Agent/Wallet/GetTransactionInformation`](/neuron-api/api-reference/wallet/get-transaction-information) | Get Transaction Information | JWT bearer |
| [`POST /Agent/Wallet/InitiateBuyEDaler`](/neuron-api/api-reference/wallet/initiate-buy-edaler) | Initiate Buy Edaler | JWT bearer |
| [`POST /Agent/Wallet/InitiateSellEDaler`](/neuron-api/api-reference/wallet/initiate-sell-edaler) | Initiate Sell Edaler | JWT bearer |
| [`POST /Agent/Wallet/ProcessEDalerUri`](/neuron-api/api-reference/wallet/process-edaler-uri) | Process Edaler Uri | JWT bearer |
## Related guides
| Guide | Operations from this resource |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Complete a development payment](/build/payments/overview) | `POST /Agent/Wallet/GetBalance`
`POST /Agent/Wallet/GetTransactionInformation` |
## Before production
Before production, confirm operation-level privileges, non-success responses, retry and replay behavior, side effects, federation, and emitted or observable events. These fields are not complete in the current specification.
## Related
* [Wallets and payments](/platform/wallets-and-payments)
* [Rate limits](/neuron-api/rate-limits)
# Process Edaler Uri
Source: https://docs.neuro-tech.io/neuron-api/api-reference/wallet/process-edaler-uri
/test-api/openapi.yaml post /Agent/Wallet/ProcessEDalerUri
Allows the client to process an eDaler URI.
## Overview
Allows the client to process an eDaler URI.
## Authentication
Requires a valid JWT bearer token.
## Notes
This endpoint uses the request schema notation described in [Pattern matching](/neuron-api/pattern-matching).
# Agent API authentication
Source: https://docs.neuro-tech.io/neuron-api/authentication
Reference for login signatures, account creation signatures, and JWTs
Use the [quickstart](/neuron-api/quickstart) for a working login. This page documents the exact values that are signed.
## Login
Create a new nonce and build this UTF-8 string:
```text theme={null}
userName:host:nonce
```
Compute Base64-encoded HMAC-SHA-256 using the **account password** as the HMAC key. Send `userName`, `nonce`, `signature`, and `seconds` to `POST /Agent/Account/Login`.
The `host` value must exactly match the HTTP host used for the request, including a non-default port and excluding the scheme and path.
## Account creation
Account creation is for a trusted backend that has an operator-issued Agent API key and secret. Without a phone number, sign:
```text theme={null}
userName:host:eMail:password:apiKey:nonce
```
With a phone number, sign:
```text theme={null}
userName:host:eMail:phoneNr:password:apiKey:nonce
```
Use the **API secret** as the HMAC key. Send the matching fields to `POST /Agent/Account/Create`. The field order, capitalization of values, empty values, and host must be identical between the message and request.
Do not put an account-creation API secret in a browser, mobile application, public repository, or downloadable client. Use the browser-based onboarding flow or a trusted backend.
## JWTs
Successful login returns a short-lived JWT. Send it on authenticated calls:
```text theme={null}
Authorization: Bearer
```
* Keep JWTs out of URLs and logs.
* The specification describes `Account/Refresh` and `Account/Logout`; verify their lifecycle behavior on the target deployment before relying on refresh or immediate invalidation.
* Treat a stolen JWT as an active credential until it expires or its deployment has demonstrably invalidated it.
## HMAC test vector
Use this deterministic vector to verify an implementation without contacting a Neuron:
```text theme={null}
userName: alice
host: neuron.example.com
nonce: fixed-nonce
password: correct horse battery staple
message: alice:neuron.example.com:fixed-nonce
HMAC-SHA-256 (Base64): KyuVbr8pHJ/FiMObl8rE+IbuwtzuC/TKuPl+I+Yjvic=
```
The repository test in `samples/trusted-backend-first-app/test/neuro-client.test.mjs` checks this vector in CI.
## Common signature failures
| Symptom | Check |
| ------------------------------------ | ---------------------------------------------------- |
| Signature rejected | Exact canonical message and UTF-8 encoding |
| Works locally but not through proxy | Host and forwarded host configuration |
| Login signing uses API secret | Login must use the account password |
| Create signing uses account password | Account creation must use the API secret |
| Intermittent replay rejection | Generate a new cryptographic nonce for every request |
# Authorization and privileges
Source: https://docs.neuro-tech.io/neuron-api/authorization-and-privileges
Separate bearer authentication from deployment-specific Agent API privileges
Authentication proves which Agent API session is calling. Authorization decides whether that account may perform the requested operation. A valid JWT does not imply access to every resource group.
## What the API description establishes
* Most operations inherit JWT bearer authentication.
* Operations with `security: []` explicitly override that bearer requirement.
* Some operation descriptions mention additional account, identity, key, or review prerequisites.
The current OpenAPI document does not provide a complete machine-readable privilege name or role requirement for every operation.
## Application checklist
1. Read the generated operation's authentication requirement.
2. Identify the account, Legal Identity, key, contract role, provider, or operator prerequisite stated by the workflow.
3. Ask the Neuron operator for the narrowest role or privilege set that satisfies those requirements.
4. Test one permitted and one denied case in the target environment.
5. Treat a bearer token and the privileges of its account as separate security decisions.
## Do not infer privileges
Do not copy privilege names from MCP scopes, administration roles, legacy pages, or a different deployment into Agent API code. Until operation-level privilege metadata is verified, the deployment owner is the source for the exact grant.
Related: [Authentication](/neuron-api/authentication), [Security and transport](/neuron-api/security-and-transport), and [OpenAPI reference](/neuron-api/api-reference/openapi/overview).
# Content types
Source: https://docs.neuro-tech.io/neuron-api/content-types
Set Content-Type and Accept correctly for Agent API requests and responses
Agent API resources use the HTTP `Content-Type` header to interpret request bodies and `Accept` to select a response representation. Send both headers even when an operation currently documents only one representation; individual resources may support additional representations over time.
## Common representations
| Media type | Meaning |
| ------------------ | -------------------------------- |
| `application/json` | JSON-encoded request or response |
| `text/plain` | Plain text |
| `text/xml` | XML document |
Most documented Agent API operations use `POST` with JSON. Follow the generated operation's request body instead of assuming every resource accepts every media type.
## JSON request
```http theme={null}
POST /Agent/Account/Info HTTP/1.1
Host:
Authorization: Bearer
Accept: application/json
Content-Type: application/json
{}
```
An operation with no input fields still receives `{}` when its request body is required.
## Binary and attachment data
Some operations represent attachment or binary content inside their documented JSON or XML request. Do not assume a generic `/files` endpoint or `multipart/form-data` contract. Use the exact request schema and encoding documented for that operation.
## Content negotiation failures
* `400 Bad Request` can indicate that the body does not match the operation's schema.
* `406 Not Acceptable` can indicate that the requested response representation is unsupported.
* `415 Unsupported Media Type` may be returned by HTTP infrastructure when the request representation is unsupported; confirm the deployed behavior before depending on it.
See [API basics](/neuron-api/api-basics) and the generated endpoint reference for operation-specific requirements.
# Error handling
Source: https://docs.neuro-tech.io/neuron-api/error-handling
Handle Agent API failures without assuming an undocumented universal error schema
Treat every non-2xx Agent API response and transport failure as an unsuccessful operation. The OpenAPI document describes successful `200` responses but does not define a universal error object, complete status-code set, or operation-specific retry rules.
Do not implement against the older example containing `error.code`, `error.message`, and `requestId`. That shape has not been established as a platform-wide contract.
## Minimum client behavior
1. Record the operation, Neuron host, HTTP status when available, and a local correlation identifier.
2. Keep credentials, JWTs, personal data, contract attachments, and unreviewed upstream bodies out of browser responses and ordinary logs.
3. Preserve the raw status and body only in a protected server-side diagnostic path when policy permits it.
4. Parse a structured error only when the specific deployment or operation documents its schema.
5. Present a stable application-owned error to an untrusted client.
The [trusted-backend sample](/get-started/trusted-backend-sample) demonstrates this boundary by returning a generic `502` owned by the sample application without exposing the upstream body.
## Retry decision
Do not infer safety from the HTTP method: most current Agent API operations use `POST`, including both reads and state-changing commands.
* Retry a read only when the application can tolerate repetition and the deployment's failure contract identifies the condition as transient.
* Do not automatically retry signing, messaging, account creation, contract mutation, token mutation, or value-moving operations without a verified idempotency or reconciliation mechanism.
* If the deployment returns a retry delay, honor the deployment's documented semantics; a `Retry-After` contract is not currently specified platform-wide.
* Bound attempts, add jitter, and surface a terminal failure rather than creating an infinite authentication or command loop.
See [Idempotency and replay](/neuron-api/idempotency-and-replay) and [Rate limits](/neuron-api/rate-limits) for the unresolved platform-wide policies.
# Events and asynchronous state
Source: https://docs.neuro-tech.io/neuron-api/events-and-asynchronous-state
Observe Agent API workflows without treating request acceptance as completion
Identity review, contract approval and signing, state-machine transitions, federation, and payment processing can outlive the HTTP request that initiated them.
The public material describes several possible observation surfaces:
| Surface | What is documented |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| Retrieval or status operation | Prefer when the workflow defines a stable identifier and a documented query |
| XMPP message retrieval | `PopMessages` returns stored messages; destructive clearing is a separate operation |
| Browser event bridge | Interactive and tab-bound; not a durable server webhook |
| MCP event tools | Depends on the MCP server actually deployed and authorized |
| Operator or provider process | Required where review or approval is manual |
The Agent API does not document one durable webhook mechanism for every operation. Confirm how the target Neuron reports completion before implementing background processing.
## State-handling pattern
1. Persist the returned domain identifier before leaving the initiating request.
2. Record an application-owned pending state.
3. Observe with the verified query, message, event, or operator-mediated mechanism.
4. Make repeated observations idempotent.
5. Distinguish approved/finalized, rejected/failed, expired, and still-pending outcomes.
6. Define a timeout and a human-visible recovery path.
See [Realtime browser events](/neuron-api/guides/webhooks) for the documented interactive bridge.
# Federation
Source: https://docs.neuro-tech.io/neuron-api/federation
Distinguish per-Neuron Agent API sessions from explicitly federated operations
An Agent API account and its JWT belong to the Neuron host that issued them. Build a separate client and session for each host.
Some documented operations can work with objects or actors on another Neuron. Examples in the current specification include retrieving or signing federated contracts and sending XMPP messages to another address. Remote Quick Login has a separate session-oriented description.
## Confirm support for each operation
* Do not send a JWT to a different host.
* Do not reuse a host-bound HMAC signature against another host.
* Do not assume every identifier can be resolved or mutated across federation.
* Use only the federation behavior explicitly described for the operation and verified on the target deployments.
* Treat acceptance by the local Neuron and completion across the network as separate states when the workflow is asynchronous.
See [Trust and federation](/platform/trust-and-federation) for the conceptual model and [Events and asynchronous state](/neuron-api/events-and-asynchronous-state) for completion handling.
# Apply for a Legal Identity
Source: https://docs.neuro-tech.io/neuron-api/guides/applying-for-a-legal-identity
Collect deployment-specific requirements, submit a signed application, and retain its state
A Legal Identity application combines deployment-required identity properties, an Agent API key reference, cryptographic signatures, and any required supporting evidence.
Required identity fields and review providers differ by deployment. Do not use older password-based payload examples; follow the generated operation pages and the signing instructions supplied for the target Neuron.
## Expected result
An identity application exists with a returned Legal Identity reference and a status that the application can monitor through review.
## Procedure
1. Retrieve `POST /Agent/Legal/GetApplicationAttributes` instead of hard-coding fields, attachment counts, country rules, or review options.
2. Collect only the properties required for the intended identity and relying workflow.
3. Normalize any personal-number data only through the supported validation operation and policy for that environment.
4. Read the generated `POST /Agent/Legal/ApplyId` schema. Bind the application to the intended key identifier, create a fresh nonce, and supply the required signatures.
5. Persist the returned Legal Identity/application reference and current status.
6. Add each required attachment using the exact `AddIdAttachment` JSON/base64 schema currently published; do not infer a multipart request.
7. Submit `ReadyForApproval` only after the required evidence is present.
## State to retain
* Account-to-application-user mapping.
* Neuron host and environment.
* Key reference used for the application.
* Legal Identity or application identifier.
* Current review status and last observation time.
* Safe correlation identifiers for support; not the identity evidence itself.
## Asynchronous behavior
Treat submission and approval as separate events. The application must keep a pending state and use the event or query mechanism confirmed for its Neuron to observe approval or rejection. A successful submission response is not approval.
## Security notes
* Keep identity evidence and personal data out of logs, URLs, analytics, and error trackers.
* Do not claim that a status is legally sufficient for the relying application without its acceptance policy.
* Do not expose key passwords, account credentials, JWTs, or unredacted attachments.
## Next
* [Get the identity reviewed](/neuron-api/guides/getting-your-identity-approved)
* [Verified identity overview](/build/verified-identity/overview)
* [Legal Identity reference](/neuron-api/api-reference/legal-identities/overview)
# Browser-based signup
Source: https://docs.neuro-tech.io/neuron-api/guides/browser-based-signup
Create and activate an Agent account from a browser without exposing an API secret
Use the web-form endpoint when an untrusted browser must create an account directly. Unlike the JSON [Create account](/neuron-api/api-reference/accounts-and-onboarding/create-account) flow, the browser flow uses reCAPTCHA and redirects rather than exposing the account-creation API key to JavaScript.
Before launch, test the form fields, allowed redirect origins, cookie attributes, CORS behavior, reCAPTCHA settings, and session-token response on the target Neuron.
## Prerequisites
The Neuron operator must:
* configure Google reCAPTCHA;
* create an API key whose owner is `Agent API` and whose account limit has not been reached;
* configure email delivery and, if phone verification is required, SMS delivery;
* serve the signup page over HTTPS.
Removing the API key or setting its limit to the current account count disables public account creation.
## Submit the form
Render the reCAPTCHA widget and submit a normal HTML form to `/Agent/Account/CreateWebForm`:
```html theme={null}
```
The endpoint consumes form data, not JSON. The redirect target must be an application URL you trust; do not copy a redirect URL from arbitrary query input.
## Recover the new session
After the Neuron redirects the browser, preserve its session cookie and exchange the creation session for account state:
```js theme={null}
const response = await fetch(
"https://neuron.example/Agent/Account/GetSessionToken",
{
method: "POST",
credentials: "include",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({})
}
);
if (!response.ok) throw new Error(`Session exchange failed: ${response.status}`);
const result = await response.json();
```
The created account starts disabled. Ask the user for the code delivered to their email and call [Verify email](/neuron-api/api-reference/accounts-and-onboarding/verify-email). If a phone number was supplied, complete [phone verification](/neuron-api/api-reference/accounts-and-onboarding/verify-phone-number) too.
Keep the returned JWT in memory where possible. Never place it in a URL, page source, analytics event, or browser log.
# Common integration patterns
Source: https://docs.neuro-tech.io/neuron-api/guides/common-integration-patterns
Keep credentials protected and handle asynchronous Agent API work safely
These application-owned patterns apply across Agent API resource groups. They do not substitute for an operation's deployed authentication, idempotency, error, or event contract.
## Keep authentication at the edge
Create a small API client that owns the Neuron base URL, signing material, JWT, and refresh policy. Business code should ask it to perform an operation rather than passing tokens throughout the application.
```js theme={null}
async function postNeuron(path, body) {
const jwt = await tokenManager.validToken();
const response = await fetch(new URL(path, neuronBase), {
method: "POST",
headers: {
Authorization: `Bearer ${jwt}`,
"Content-Type": "application/json",
Accept: "application/json"
},
body: JSON.stringify(body)
});
if (!response.ok) throw await NeuronError.from(response);
return response.json();
}
```
Add refresh only after its deployed lifecycle has been verified. Bound it to one attempt so an invalid credential or disabled account cannot create an authentication loop.
## Separate command and retrieval paths
Treat operations such as signing, sending a message, transferring value, or changing a contract as commands. Do not automatically retry them unless the endpoint has an idempotency mechanism or you can prove from the returned identifier that the command did not run.
Queries and reads may be safer to repeat, but the platform-wide transient status set and `Retry-After` behavior are not currently specified. Retry only conditions verified for the deployment, with a bounded attempt count and jitter.
## Poll incrementally
Use pagination only where the operation schema actually defines a bound, cursor, offset, or continuation value. For message retrieval, process a returned batch transactionally before invoking a separate destructive clear operation.
## Preserve domain boundaries
An Agent account and its JWT belong to one Neuron. Keep a separate client/session per host. Before multi-Neuron actions:
* identify which host owns the account or object;
* use federation, XMPP, or Remote Quick Login for cross-domain interaction;
* never replay a host-bound signature or bearer token against another domain;
* do not assume a local operation can read or modify a foreign object unless its operation description explicitly documents federation.
## Decode structured failures
Branch first on HTTP status, then parse the response body only when its schema is known. Log a local correlation ID, operation, host, and status—but never credentials, JWTs, legal documents, raw contract attachments, or personal identifiers. See [Error handling](/neuron-api/error-handling).
## Make event processing idempotent
XMPP, browser events, queues, and external services can redeliver work. Persist a stable message, contract, token, or business-operation ID before applying side effects. A duplicate should return the previously committed result.
# Follow the contract API lifecycle
Source: https://docs.neuro-tech.io/neuron-api/guides/contracts-flow
Create a contract, prepare a proposal, collect signatures, and retrieve the result
Contracts are created and signed using Legal Identities. The API description does not include a request body for `POST /Agent/Legal/SendProposal`, while the JavaScript client sends an XML proposal over XMPP.
This page is a lifecycle map, not a copy-paste tutorial. Ask the Neuron operator which proposal transport and XML namespace the deployment supports before sending a proposal.
## Lifecycle
```mermaid theme={null}
sequenceDiagram
participant Client
participant Neuron
Client->>Neuron: Legal/CreateContract
Neuron-->>Client: Contract object
Client->>Neuron: Legal/SendProposal (payload not documented)
Neuron-->>Client: Success response (shape not documented)
Client->>Neuron: Legal/SignContract (signed request)
Neuron-->>Client: Contract object
```
## Follow the lifecycle
1. Create a contract from an approved template with `Legal/CreateContract`. The documented response contains a `Contract` object.
2. Obtain the deployment's verified proposal transport, XML namespace or JSON body, and recipient semantics before sending anything to a counterparty.
3. Show the exact contract and role to the signer.
4. Construct and verify all fields required by `Legal/SignContract`: `keyId`, `legalId`, `contractId`, `role`, `nonce`, `keySignature`, and `requestSignature`.
5. Retrieve signed or created contracts with `Legal/GetSignedContracts` and `Legal/GetCreatedContracts`.
## Related endpoints
* [Propose a contract template](/neuron-api/api-reference/contracts/propose-contract-template)
* [Create a contract](/neuron-api/api-reference/contracts/create-contract)
* [Send a proposal](/neuron-api/api-reference/contracts/send-proposal)
* [Sign a contract](/neuron-api/api-reference/contracts/sign-contract)
* [Get contract](/neuron-api/api-reference/contracts/get-contract)
# Create an account from a trusted backend
Source: https://docs.neuro-tech.io/neuron-api/guides/creating-an-account
Create and verify an account from a backend that can protect the API secret
Use this guide only when a trusted backend can protect the operator-issued account-creation API key and secret. For public clients, use [browser-based signup](/neuron-api/guides/browser-based-signup).
Account creation requires an operator-issued API key and secret. Use the generated operation page for request fields, and confirm contact-verification and error behavior on the target Neuron.
## Expected result
```text theme={null}
Operator-approved creation credentials
↓
Account creation request signed for the exact Neuron host
↓
Required email and phone verification
↓
Enabled account and a fresh authenticated session
```
## Prerequisites
* Exact Neuron host and environment semantics.
* Account-creation API key and secret from that Neuron's operator.
* Operator-confirmed account quota and verification policy.
* A trusted backend secret store.
* A user interaction for collecting and confirming required contact details.
## Procedure
1. Optionally retrieve `GET /Agent/Account/DomainInfo` and confirm the user selected the intended Neuron.
2. Read the generated `POST /Agent/Account/Create` schema and its signature message. Sign the documented canonical message with the API secret; do not replace it with a signature over only the nonce.
3. Submit the account request from the backend and retain only the safe identifiers, status, and session state the application needs.
4. Complete the required `VerifyEMail` and `VerifyPhoneNr` operations for the deployment.
5. Establish a fresh session through the verified login flow rather than assuming the creation response represents a fully enabled account.
6. Retrieve `Account/Info` and verify the resulting account state.
## Security notes
* Never send the account-creation API secret to a browser or mobile binary.
* Bind every signature to the exact documented fields and host.
* Generate a fresh unpredictable nonce for every signed request.
* Do not log passwords, secrets, nonces, verification codes, or returned JWTs.
* Apply user-interface throttling without inventing undocumented server rate limits or retry windows.
## Verification
The workflow is complete only when the account state returned by the target Neuron satisfies its activation policy and the user can establish a new session. Account activation does not create or approve a Legal Identity.
## Next
* [Create a cryptographic key](/neuron-api/guides/creating-cryptographic-keys)
* [Apply for a Legal Identity](/neuron-api/guides/applying-for-a-legal-identity)
* [Accounts and onboarding reference](/neuron-api/api-reference/accounts-and-onboarding/overview)
# Create an Agent API cryptographic key
Source: https://docs.neuro-tech.io/neuron-api/guides/creating-cryptographic-keys
Choose an algorithm, create encrypted key material through the Neuron, and retain its reference
Agent API key creation asks the Neuron to create and store encrypted key material for supported signing workflows. This differs from a direct XMPP client that manages its own private keys.
`CreateKey` requires identifiers, a nonce, and signatures. Do not replace the documented request with an older password-only example; confirm signature construction on the target Neuron.
## Expected result
```text theme={null}
Authenticated Agent API session
↓
Supported algorithm selected
↓
Signed key-creation request
↓
Encrypted key stored by the Neuron
↓
Stable key reference retained for identity and signing workflows
```
## Procedure
1. Call `POST /Agent/Crypto/GetAlgorithms` with the documented empty JSON body.
2. Select an algorithm accepted by the relying identity or contract workflow; do not hard-code an algorithm merely because one Neuron returns it.
3. Read the generated `POST /Agent/Crypto/CreateKey` schema for the target documentation version.
4. Construct `localName`, `namespace`, the documented key identifier, a fresh nonce, and the required signatures using a maintained SDK or verified implementation helper.
5. Submit the request and retain the exact identifier fields used by later operations.
6. Retrieve the public key through `POST /Agent/Crypto/GetPublicKey` when the relying workflow needs verification material.
## State to retain
| Value | Why |
| --------------------------------------------------- | ---------------------------------------------------------- |
| Neuron host | Key references are deployment-bound |
| Local name and namespace | Locate the application key without relying on display text |
| Key identifier required by later operations | Bind identity and signing requests to the intended key |
| Algorithm and creation metadata returned by the API | Support validation, rotation, and audit decisions |
Never store a key password or account password beside these identifiers. The generated reference is authoritative for field names; this guide does not invent a response-level `keyId` where the API does not return one.
## Next
* [Keys and signatures](/platform/keys-and-signatures)
* [Apply for a Legal Identity](/neuron-api/guides/applying-for-a-legal-identity)
* [Cryptography reference](/neuron-api/api-reference/cryptography/overview)
# Observe Legal Identity review
Source: https://docs.neuro-tech.io/neuron-api/guides/getting-your-identity-approved
Select a supported review method and handle pending, approved, or rejected outcomes
Identity review begins after the application contains the required properties and evidence and is marked ready according to the target Neuron's policy.
Review providers, exact state labels, peer-review rules, and notification mechanisms are deployment-specific and still require verification. Do not assume that approval creates a wallet or enables another capability unless the operator documents that behavior.
## Choose the deployed review method
Use `GetApplicationAttributes` and the supported service-provider operations to discover what the Neuron actually offers. A deployment might use operator review, an identity review service, peer review, or another configured policy.
If the chosen reviewer requires explicit access, grant only the documented identity access for that review and record how it is revoked afterward.
## Application state model
```text theme={null}
Draft in application
↓
Submitted to Neuron
↓
Pending review
├── approved/current
└── rejected or correction required
```
Use the status returned by `GetIdentity` rather than mapping it to a guessed enum. Store the raw status plus the application state your user interface needs.
## Observe completion
1. Persist the Legal Identity/application identifier returned earlier.
2. Use the event, message, callback, or polling mechanism confirmed for the target Neuron.
3. Make repeated observations idempotent so the same result is not applied twice.
4. Retrieve the current identity before enabling a trust-dependent application action.
5. Surface rejection or correction information without leaking identity evidence.
## Completion
The workflow is complete when the relying application has retrieved the identity's current status and evaluated it against its own provider and assurance policy. “Request accepted” and “review pending” are not successful identity verification.
## Next
* [Agreements](/build/agreements/overview)
* [Tokenized assets](/build/tokenized-assets/overview)
* [Trust and federation](/platform/trust-and-federation)
# Legal Identity flow
Source: https://docs.neuro-tech.io/neuron-api/guides/legal-identity-flow
Map the key, application, evidence, submission, and review checkpoints
Use this map to coordinate account, key, application, evidence, and review state. Open the linked guides for procedures and the API reference for exact fields.
Required fields, review providers, and status delivery differ by deployment. Confirm them with the Neuron operator before implementing the full sequence.
```text theme={null}
Account active for the required operations
↓
Create and retain a cryptographic key reference
↓
Get deployment-specific application requirements
↓
Submit the signed Legal Identity application
↓
Attach the required evidence
↓
Mark ready for approval
↓
Observe pending → approved/current or rejected
```
## Checkpoints
| Checkpoint | Do not continue until |
| ------------ | ----------------------------------------------------------------------------------- |
| Account | The target Neuron reports the account state required by the operation |
| Key | The application retained the exact key reference used for signing |
| Requirements | Required properties, evidence, and review options came from the target deployment |
| Application | The Legal Identity/application identifier and status were persisted |
| Submission | Required attachments are present and `ReadyForApproval` succeeded |
| Review | The current identity was retrieved and accepted by the relying application's policy |
## Related guides
* [Create an account](/neuron-api/guides/creating-an-account)
* [Create a key](/neuron-api/guides/creating-cryptographic-keys)
* [Apply for a Legal Identity](/neuron-api/guides/applying-for-a-legal-identity)
* [Observe review](/neuron-api/guides/getting-your-identity-approved)
* [Verified identity overview](/build/verified-identity/overview)
# Login flows
Source: https://docs.neuro-tech.io/neuron-api/guides/login-flows
Choose an Agent API, browser-session, remote, or OAuth login flow
Neuron has two related authentication surfaces in the available specifications: Agent API JWTs authorize HTTP API calls, while HTTP session login authorizes browser access to hosted pages and administration.
Only direct Agent API login has a runnable example. Test OAuth, Quick Login, Remote Quick Login, browser sessions, refresh, and logout on the target Neuron before choosing one.
| Client | Start with | Result |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| First-party back end with Agent credentials | [Login](/neuron-api/api-reference/authentication-and-sessions/login) | Agent API JWT. |
| Browser or native app acting for a user | [OAuth Authorization Code with PKCE](/protocols/oauth) | Scoped OAuth access and optional refresh token. |
| Terminal, appliance, or input-constrained device | [OAuth device authorization](/protocols/oauth) | Scoped OAuth access after approval on another device. |
| Browser already authenticated with Quick Login | [Quick login](/neuron-api/api-reference/authentication-and-sessions/quick-login) | Agent API JWT for an account on the same Neuron. |
| Browser opening a different Neuron | Prepare locally, then [remote quick login](/neuron-api/api-reference/authentication-and-sessions/remote-quick-login) remotely | HTTP session on the remote Neuron; no remote Agent JWT. |
| Legacy HTTP-auth client | [WWW login](/neuron-api/api-reference/authentication-and-sessions/www-login) | Agent API JWT. Prefer another flow for new work. |
## Direct Agent login
The direct flow sends the login request, receives `jwt` and `expires`, and uses the token as `Authorization: Bearer `. The specification describes [Refresh](/neuron-api/api-reference/authentication-and-sessions/refresh) and [Logout](/neuron-api/api-reference/authentication-and-sessions/logout); verify their deployed lifecycle behavior before depending on it.
Use the Agent API's documented signing rules. A request signed for a different host or a reused nonce can fail even when the username and password are correct.
## Documented Quick Login shape
Quick Login depends on the current HTTP session, so send cookies:
```js theme={null}
const response = await fetch("/Agent/Account/QuickLogin", {
method: "POST",
credentials: "include",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ seconds: 900 })
});
const { jwt, userName, expires } = await response.json();
```
## Documented Remote Quick Login sequence
1. On the Neuron where the Agent is connected, call `PrepareRemoteQuickLogin` with its JWT and retain `legalId`.
2. In the browser session for the target Neuron, call `RemoteQuickLogin` with that Legal ID and a user-visible purpose.
3. The user's client receives and signs the petition.
4. Inspect `loggedIn` and `petitionSent`. Confirm that successful approval creates the expected HTTP session on the target Neuron.
Do not assume the remote call creates an Agent API JWT for the remote broker. If an administrator-associated identity can gain administrative access, confirm the required permissions and approval UI before enabling the flow.
## Token handling
* Request the shortest practical lifetime; Agent endpoints limit `seconds` to 3600.
* Store refresh tokens only in encrypted server-side or platform-protected storage.
* Validate `expires` instead of assuming a lifetime.
* Never send a token to a different Neuron host.
* Treat account, legal-identity, and OAuth scopes as separate authorization decisions.
# Send XMPP messages
Source: https://docs.neuro-tech.io/neuron-api/guides/messaging
Send text or formatted XMPP chat messages
Neuron uses XMPP for messaging. The Agent API lets you send messages without a persistent XMPP connection.
## Message sequence
```mermaid theme={null}
sequenceDiagram
participant Client
participant Neuron
Client->>Neuron: Account/Login (HMAC)
Neuron-->>Client: JWT
Client->>Neuron: Xmpp/SendTextMessage (JWT)
Neuron-->>Client: sent + message id
Client->>Neuron: Xmpp/SendFormattedMessage (JWT)
Neuron-->>Client: sent + message id
```
## Find the recipient JID
A JID is the XMPP address of a user, such as `alice@neuron.example.com`. You can retrieve JIDs from your roster or directory services provided by your Neuron.
## Send a message
* [Send text messages](/neuron-api/api-reference/messaging/send-text-message)
* [Send formatted messages](/neuron-api/api-reference/messaging/send-formatted-message)
# Inspect tokens and event history
Source: https://docs.neuro-tech.io/neuron-api/guides/tokens-flow
Retrieve Neuro-Features, creation attributes, notes, and events
Tokens represent signed assets or proofs that can be linked to contracts and state machines. This guide shows how to inspect token metadata and history.
This is an inspection flow, not a token-creation flow. Neuro-Features are created through approved creation contracts, optionally containing a state-machine definition. See the [contract quickstart](/contracts/quickstart).
## Request sequence
```mermaid theme={null}
sequenceDiagram
participant Client
participant Neuron
Client->>Neuron: Tokens/GetTokens
Neuron-->>Client: list
Client->>Neuron: Tokens/GetToken
Neuron-->>Client: token details
Client->>Neuron: Tokens/GetTokenEvents
Neuron-->>Client: event history
```
## Related operations
* [Get creation attributes](/neuron-api/api-reference/tokens/get-creation-attributes)
* [Add text note](/neuron-api/api-reference/tokens/add-text-note)
* [Add XML note](/neuron-api/api-reference/tokens/add-xml-note)
* [Get contract tokens](/neuron-api/api-reference/tokens/get-contract-tokens)
# User onboarding
Source: https://docs.neuro-tech.io/neuron-api/guides/user-onboarding
Create, verify, and activate a Neuron account
Use this flow when you want to create a Neuron account from a trusted back-end service and guide the user to a verified, active session.
Required account fields, contact verification, identity providers, and review behavior differ by deployment. Confirm them with the Neuron operator before implementing the complete sequence.
## Account creation sequence
```mermaid theme={null}
sequenceDiagram
participant Client
participant Neuron
Client->>Neuron: Account/DomainInfo (optional)
Client->>Neuron: Account/Create (HMAC + API key)
Neuron-->>Client: JWT + disabled account
Client->>Neuron: Account/VerifyEMail (code)
Neuron-->>Client: verified
Client->>Neuron: Account/Login (HMAC)
Neuron-->>Client: JWT
```
## Create and verify the account
1. Optional: call `Account/DomainInfo` to show a human-friendly domain name.
2. Call `Account/Create` to create the account and receive an initial JWT.
3. Prompt the user to enter the email verification code.
4. Call `Account/VerifyEMail` to enable the account.
5. Call `Account/Login` to obtain a fresh JWT for ongoing use.
Read the generated operation pages before implementing each request. Do not copy older account-creation examples that sign only a nonce; account creation and login use different secrets and different canonical messages.
## Common pitfalls
* Reusing a nonce will invalidate the request.
* An unverified account cannot use most endpoints.
* If login fails after verification, check the host used for signing.
## Add a Legal Identity
* Continue to [Legal Identity flow](/neuron-api/guides/legal-identity-flow).
* Review [Authentication](/neuron-api/authentication).
# Realtime browser events
Source: https://docs.neuro-tech.io/neuron-api/guides/webhooks
Route incoming XMPP messages to a live browser tab through Neuron's event channel
The Agent API does not expose a generic server-to-server webhook registration endpoint. It can route matching incoming XMPP messages to a live browser tab through Neuron's client-event system. Use this for interactive applications; use [message polling](/neuron-api/api-reference/messaging/pop-messages) or your own durable queue consumer for background processing.
Browser events are interactive, not a durable server-to-server webhook. Test delivery, cookies, allowed origins, disconnects, and reconnection on the target Neuron.
## 1. Load the event client
Include `/Events.js` from the Neuron so the page receives a tab ID and maintains its event channel. When the page and API use different hosts, declare the event server in the page metadata as required by that deployment and configure the Agent client host with `AgentAPI.IO.SetHost(host, secure)`.
Cross-origin deployments also need correct CORS, cookie, and TLS configuration. Do not relax origins globally to make the event channel work.
## 2. Register a handler
After the event client has assigned a tab ID, register the most specific match you need:
```http theme={null}
POST /Agent/Xmpp/RegisterEventHandler HTTP/1.1
Authorization: Bearer
Content-Type: application/json
{
"localName": "alert",
"namespace": "urn:example:alerts:1",
"type": "normal",
"function": "onAlert",
"tabId": ""
}
```
All match fields are optional. A specific local name and namespace wins over a broader fallback. `function` names the browser callback. Leaving it empty unregisters that match.
```js theme={null}
window.onAlert = event => {
// Validate the event shape and escape any rendered message content.
console.log("Alert received", event);
};
```
When a message matches a live registration, Neuron pushes it to the tab instead of storing it as an offline message. Therefore, browser delivery is not durable.
## 3. Design for disconnects
* register again when a page reloads or receives a new tab ID;
* make handlers idempotent because reconnect races can cause repeat work;
* poll [Pop messages](/neuron-api/api-reference/messaging/pop-messages) after reconnect when missing a message is unacceptable;
* use the narrowest local-name, namespace, and stanza-type match;
* unregister handlers no longer needed by sending the same selector with an empty `function`.
The older documentation called this a webhook. It is a browser event bridge tied to a Neuron session and tab, not a public callback URL.
# Idempotency and replay
Source: https://docs.neuro-tech.io/neuron-api/idempotency-and-replay
Avoid duplicating Agent API commands while idempotency remains operation-specific
The OpenAPI document does not define a platform-wide idempotency header, idempotency-key store, or replay window.
## Safe default
Classify an operation before retrying it:
| Operation kind | Default behavior |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Read or inspection | A bounded retry may be acceptable after verifying the deployment's transient failures |
| Create, sign, send, transfer, clear, delete, or initiate | Do not automatically retry without reconciliation or a verified idempotency contract |
| Login or signed request | Generate a fresh nonce for a new attempt; never replay the identical signed request |
## Application-owned reconciliation
Where the API accepts a stable identifier, generate and persist it before sending the command. After an ambiguous failure, query by that identifier before deciding to issue another command. This is an application pattern, not proof that every endpoint deduplicates it.
For value movement, signatures, contracts, identity submissions, and messages, obtain operation-specific rules from the Neuron operator before enabling automated retries.
# Agent API
Source: https://docs.neuro-tech.io/neuron-api/introduction
Use HTTPS to work with accounts, identities, contracts, tokens, messaging, and storage
The Agent API is the Neuron's application-facing HTTP API. Use it from a web service or backend that does not maintain its own XMPP connection.
All endpoints belong to a specific Neuron:
```text theme={null}
https:///Agent/...
```
There is no shared platform-wide API host.
## Start with an existing account
The quickest first test is to obtain a Neuron account from its operator, log in, and call `Account/Info`. Account creation requires a separate API key and secret.
Run a complete Node.js example using an existing account.
## Find an API area
| Area | Typical use |
| ---------------- | --------------------------------------------- |
| Accounts | Login, sessions, verification, and onboarding |
| Legal Identities | Apply, review, retrieve, and authorize access |
| Contracts | Propose templates, create instances, and sign |
| Tokens | Inspect Neuro-Features, events, and reports |
| Messaging | XMPP messages, contacts, presence, and events |
| Storage | Private XML and vault operations |
Most calls use a short-lived JWT in the `Authorization` header. Login and account creation instead use an HMAC signature in the JSON body.
## Choose another interface when
* you are learning or visually editing contract XML: use [LegalLab](/contracts/legallab-quickstart);
* an AI client needs a bounded tool interface that the target Neuron operator has verified and enabled: review [MCP](/mcp/overview);
* code must run inside the Neuron process: build a [Neuron package](/neuron-development/quickstart).
# Assignment pattern notation
Source: https://docs.neuro-tech.io/neuron-api/pattern-matching
Read the assignment pattern-matching notation used to describe Agent API inputs
Some legacy Agent API pages describe input content using Neuron Script assignment pattern-matching notation. This notation documents request shape and validation; it is not an HTTP query-filter language.
## Common patterns
| Pattern | Meaning |
| ------------------------------------- | -------------------------------------------------- |
| `Required(Str(PUserName))` | A required string assigned to `PUserName` |
| `Optional(Int(PSeconds))` | An optional integer assigned to `PSeconds` |
| `Required(Int(0 < PSeconds <= 3600))` | A required integer satisfying the stated range |
| `Optional(DateTime(PExpires))` | An optional date-time value assigned to `PExpires` |
## How to read a pattern
1. The outer `Required` or `Optional` expression describes presence.
2. The inner expression describes the expected value type.
3. A condition inside the type expression describes validation.
4. The `P...` variable names correspond to values consumed by the resource implementation; the JSON field names come from the operation's documented request schema.
## Canonical application contract
Application developers should use the generated OpenAPI schema for exact JSON field names, types, and required properties. Pattern notation remains documented so legacy examples and implementation-oriented reference material can be interpreted correctly.
Do not translate these expressions into `GET /v1/...?...` filters. The Agent API publishes resources below `/Agent` and normally uses `POST` unless an individual resource states otherwise.
# Agent API quickstart
Source: https://docs.neuro-tech.io/neuron-api/quickstart
Log in and make a first authenticated request
This quickstart uses an existing account. It signs login correctly, obtains a JWT, and calls `Account/Info`.
## Prerequisites
* Node.js 18 or later.
* A Neuron host, username, and password supplied by the operator.
* HTTPS access to that Neuron.
## 1. Set credentials for this terminal
```powershell PowerShell theme={null}
$env:NEURON_HOST = "neuron.example.com"
$env:NEURON_USER = "alice"
$env:NEURON_PASSWORD = ""
```
```bash macOS/Linux theme={null}
export NEURON_HOST="neuron.example.com"
export NEURON_USER="alice"
export NEURON_PASSWORD=""
```
`NEURON_HOST` is the exact HTTP host, including the port when it is not the default. Do not include `https://` or a path.
## 2. Create `quickstart.mjs`
```javascript theme={null}
import { createHmac, randomBytes } from "node:crypto";
const host = process.env.NEURON_HOST;
const userName = process.env.NEURON_USER;
const password = process.env.NEURON_PASSWORD;
if (!host || !userName || !password) {
throw new Error("Set NEURON_HOST, NEURON_USER, and NEURON_PASSWORD.");
}
const nonce = randomBytes(32).toString("base64url");
const message = `${userName}:${host}:${nonce}`;
const signature = createHmac("sha256", password)
.update(message, "utf8")
.digest("base64");
const loginResponse = await fetch(`https://${host}/Agent/Account/Login`, {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json"
},
body: JSON.stringify({ userName, nonce, signature, seconds: 3600 })
});
if (!loginResponse.ok) {
throw new Error(`Login failed (${loginResponse.status}): ${await loginResponse.text()}`);
}
const login = await loginResponse.json();
const infoResponse = await fetch(`https://${host}/Agent/Account/Info`, {
method: "POST",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
Authorization: `Bearer ${login.jwt}`
},
body: "{}"
});
if (!infoResponse.ok) {
throw new Error(`Account/Info failed (${infoResponse.status}): ${await infoResponse.text()}`);
}
console.log(await infoResponse.json());
console.log(`JWT expires at ${login.expires}`);
```
## 3. Run it
```bash theme={null}
node quickstart.mjs
```
Success is an account information response followed by the JWT expiry time. The script keeps the JWT in memory and does not print it.
## Why the signature has this form
Login signs this exact UTF-8 message with the **account password** as the HMAC-SHA-256 key:
```text theme={null}
userName:host:nonce
```
Changing the host, omitting a non-default port, or reusing a nonce makes the request invalid. See [Authentication](/neuron-api/authentication) for account-creation signatures and token handling.
## Next
* [Create contracts with the Agent API](/contracts/agent-api-quickstart)
* [Legal Identity flow](/neuron-api/guides/legal-identity-flow)
* [API reference](/neuron-api/api-reference/overview)
# Rate limits
Source: https://docs.neuro-tech.io/neuron-api/rate-limits
Plan for deployment-specific Agent API limits without assuming undocumented headers
The OpenAPI document does not define a platform-wide request quota, burst limit, `429` response schema, or `Retry-After` behavior.
Before production, obtain from the Neuron operator:
* limits by account, credential, IP, operation, and time window;
* whether login, recovery, creation, messaging, and value-moving operations have separate limits;
* the response status, headers, and body used when a limit is reached;
* the correct retry delay and escalation path;
* monitoring signals for sustained throttling.
Clients should bound concurrency and retry attempts even when the deployment publishes no limit. Do not interpret an absent published limit as unlimited capacity.
# Requests and responses
Source: https://docs.neuro-tech.io/neuron-api/requests-and-responses
Build Agent API requests from the generated operation pages
Use the generated operation page as the contract for path, method, security override, required fields, and documented success shape.
## Requests
* Build URLs as `https:///Agent//`.
* Use the generated method. Most current operations use `POST`; `GET /Agent/Account/DomainInfo` is the documented exception.
* Send `Content-Type: application/json`.
* Send `{}` when a documented `POST` operation has an empty JSON request.
* Preserve field names and capitalization exactly; examples include both lower-camel-case fields and capitalized collection fields.
* Do not add a shared `/v1` prefix.
## Responses
The specification documents `200` success responses. Some contain a JSON object with required fields, some allow additional deployment fields, and some have no documented body schema. Validate required fields before using them and ignore unknown fields unless the operation says otherwise.
A `200` response shape does not establish business completion for an asynchronous workflow. Persist the returned identifier and observe the later state using the mechanism verified for that workflow.
Non-success response bodies are not yet defined by one platform-wide schema. See [Error handling](/neuron-api/error-handling).
# Security and transport
Source: https://docs.neuro-tech.io/neuron-api/security-and-transport
Protect Agent API credentials and verify deployment-specific transport controls
## TLS / HTTPS
Agent API URLs use HTTPS:
```text theme={null}
https://
```
Use the exact host supplied by the operator. The public documentation does not yet define a platform-wide minimum TLS version, certificate policy, mutual-TLS option, proxy topology, or IP-allowlisting contract. Obtain those controls from the deployment owner before production.
## Credential management
* Store account passwords, account-creation API keys and secrets, and JWTs in a secrets manager or protected runtime configuration—never hardcode them.
* Never log full JWT tokens or HMAC secrets in your application logs.
* If a credential may be compromised, stop using it and follow the rotation or account-recovery procedure supplied by the Neuron operator. A universal rotation API is not currently documented.
## Keep trusted credentials out of public clients
* Never embed an account-creation API secret or trusted account password in browser or mobile code.
* Put trusted Agent API calls behind an application backend.
* Return only fields the user-facing client needs.
* Keep JWTs out of URLs, analytics, crash reports, and browser-visible errors.
* Verify cookies, CORS, redirect origins, and CSRF protection for the exact browser flow and deployment.
## Storage and logging
The documentation does not establish one encryption-at-rest algorithm or automatic masking policy for every Neuron deployment. Classify the data your application stores, minimize it, encrypt it according to the deployment's approved policy, and redact logs at the application boundary.
Never log account passwords, API secrets, full JWTs, authorization headers, private keys, or unreviewed identity and contract payloads.
# Versioning and compatibility
Source: https://docs.neuro-tech.io/neuron-api/versioning
Identify Agent API URLs and confirm compatibility with your Neuron version
Agent API resources are published below the per-Neuron `/Agent` path. The documentation currently has no verified basis for a shared central `/v1` base URL, so examples must not use one.
## URL model
```text theme={null}
https:///Agent//
```
For example:
```text theme={null}
https://neuron.example.com/Agent/Account/Info
```
## Confirm compatibility
Neuro does not currently publish a platform-wide compatibility, deprecation, or sunset policy. Until one is available:
* do not claim a `v1` URL contract;
* do not claim a fixed deprecation window;
* do not claim that a particular HTTP status will be used after sunset;
* record the tested Neuron build or deployment alongside executable examples;
* test the documented operations against the Neuron build you will use before release.
A successful request against one Neuron deployment does not establish a platform-wide compatibility guarantee. Confirm the deployed build and operator policy before production rollout.
## Ask the operator
Before production, ask how the deployment handles:
1. How a client identifies the API/runtime version.
2. Which changes are considered additive or breaking.
3. How deprecations are announced.
4. How long deprecated behavior remains available.
5. How generated SDKs map to compatible Neuron builds.
6. Where release notes and migration guides are published.
# Build a distributable package
Source: https://docs.neuro-tech.io/neuron-development/building-packages
Create and sign a package from a tested manifest
Use this process after the manifest installs successfully on a development Neuron.
## Prerequisites
* A complete manifest and all referenced files in one output tree.
* Waher.Utility.Install and Waher.Utility.Sign from the target Neuron distribution.
* An operator-approved signing key.
* An optional package-encryption key.
## Create the package
From the build output:
```powershell theme={null}
$Installer = ""
& $Installer -p ".\HelloNeuron.package" -m ".\HelloNeuron.manifest"
```
To encrypt the package, add an installation key:
```powershell theme={null}
& $Installer -p ".\HelloNeuron.package" -k "" -m ".\HelloNeuron.manifest"
```
Do not rename an encrypted package. Its filename participates in key derivation.
## Sign the package
```powershell theme={null}
$Signer = ""
& $Signer -c ed448 -priv "" -o ".\HelloNeuron.signature" -s ".\HelloNeuron.package"
```
The result is:
```text theme={null}
HelloNeuron.package
HelloNeuron.signature
```
Keep the private signing key outside the project and Neuron host. The target Neuron or its package catalog must trust the corresponding public key.
## Verify before distribution
1. Install the package in a disposable Neuron.
2. Confirm the module starts.
3. Exercise its public endpoints.
4. Restart the Neuron and repeat the check.
5. Test upgrade and rollback.
See [Install packages](/neuron-development/installing-packages).
# Neuro.Content.OpenApi
Source: https://docs.neuro-tech.io/neuron-development/first-party-packages/neuron-content-openapi/index
Read and write OpenAPI 3.0 documents from a Neuron package
Neuro.Content.OpenApi is a public NuGet package containing a typed OpenAPI document model and a Waher JSON content codec.
## Install
```bash theme={null}
dotnet add package Neuro.Content.OpenApi --version 1.1.2
```
Match the version to the target Neuron when it already supplies this assembly.
## Create a document
```csharp theme={null}
using Neuro.Content.OpenApi.Model;
OpenApiDocument document = new OpenApiDocument
{
Info = new OpenApiInfo
{
Title = "Example API",
Version = "1.0.0"
}
};
document.Servers.Add(new OpenApiServer
{
Url = "https://neuron.example.com"
});
```
## Parse JSON
```csharp theme={null}
using System.Collections.Generic;
using Neuro.Content.OpenApi.Model;
using Waher.Content;
Dictionary data =
(Dictionary)JSON.Parse(json);
OpenApiDocument document =
OpenApiDocument.FromDictionary(data);
```
## Serialize
```csharp theme={null}
Dictionary data = document.ToDictionary();
string json = JSON.Encode(data, false);
```
Use this package when your module needs to manipulate an OpenAPI document. It does not discover HTTP routes or generate an API description from controllers.
# HTTP, content, and protocol extensions
Source: https://docs.neuro-tech.io/neuron-development/http-content-and-protocols
Choose the native extension point for APIs, web content, converters, XMPP, Things, Script, and MCP
Neuron favors small interfaces discovered through runtime inventory. Choose the extension point that matches the protocol boundary.
| Need | Primary extension point |
| ------------------------ | --------------------------------------------------------------------------------------- |
| HTTP endpoint | `Waher.Networking.HTTP.HttpResource` or the packaged controller router |
| Agent API operation | `IAgentResource` derived from the Agent resource bases |
| Media type or conversion | `Waher.Content` encoders, decoders, and converters |
| Dynamic website | Markdown metadata + Script + `.ws` resources + JavaScript |
| XMPP behavior | Register IQ/message/presence handlers on the appropriate client/component/server object |
| Physical/virtual device | `Waher.Things` nodes, sensor readout, control parameters, commands, and queries |
| Script function | Derive from the appropriate `Waher.Script` function node and expose argument metadata |
| MCP tool/prompt/resource | `McpServerTool`, `McpServerPrompt`, or an MCP resource provider |
## HTTP resources
Register one owned resource during module startup and unregister that same instance during shutdown. Declare supported methods, authentication schemes, user-session use, content negotiation, and synchronous/asynchronous behavior explicitly. Parse and bound the request before reading large bodies or contacting other services.
For application-style APIs, the Neuron HTTP Router adds controllers, nested routes, binding, middleware, authorization, and generated OpenAPI. Keep controllers thin and place business policy behind services.
## Agent resources
The Agent module discovers `IAgentResource` implementations and registers them below `/Agent`. Existing endpoint classes are the executable pattern:
* constructor: resource path and JSON/XML pattern expressions;
* `GetAuthenticationSchemes`: public, signed, JWT, or other authentication;
* `POST`: consume validated pattern variables and return a named dictionary/XML result;
* paired `.req` resources: canonical input schemas;
* paired integration fixtures/tests: contract protection.
When adding an operation, update JSON and XML together or explicitly document that only one representation is supported.
## Content negotiation
`InternetContent` locates encoders, decoders, and converters by media type. Registering a converter can affect calls across the process, including MCP Internet Content and Markdown rendering. Preserve charset, filename, content type, and errors; never reinterpret arbitrary bytes as text.
## XMPP handlers
Register the narrowest local-name and namespace pair. Validate stanza type, sender/full JID, target node, tokens, and provisioning before acting. Save the exact delegate for unregistration. IQ handlers must return either a result or a standards-compliant error and must not leave requests hanging.
## Things adapters
Implement the smallest capabilities supported by the backing device. Sensor reads should stream typed fields and errors; control parameters should validate before side effects; concentrator nodes need stable extended addresses; commands and queries must advertise support rather than relying on product type.
## Global extension risks
Inventory-based converters, Script functions, handlers, and content types can collide globally. Before shipping, search the combined runtime for route, local-name/namespace, function, and media-type conflicts and start a host containing the entire production assembly set.
# Install a package
Source: https://docs.neuro-tech.io/neuron-development/installing-packages
Install a local manifest or a signed package
Use direct manifest installation for a local development loop. Use a signed package for distribution.
## Install a local manifest
Stop the Neuron before installing an assembly:
```powershell theme={null}
Stop-Service -Name ""
& "" -m "\HelloNeuron.manifest" -s "\Waher.IoTGateway.Svc.exe" -d "" -v
Start-Service -Name ""
```
This copies files directly from the manifest and updates the local runtime installation.
## Install a signed package
Use the Neuron software administration page to upload:
* the package file;
* its signature file;
* the installation key when the package is encrypted.
Package installation requires administrative trust. An application account or MCP client should not receive package-installation privileges.
## Verify
* Confirm the package appears in the installed-software list.
* Check startup events for the module name.
* Call one package endpoint or open one installed content page.
* Check the exception log.
## Roll back
Keep the previously tested package and its installation information. If startup fails, stop the Neuron, restore the previous package or backup, and restart. Do not repeatedly restart a failing assembly package without inspecting the startup exception.
# Develop on a Neuron
Source: https://docs.neuro-tech.io/neuron-development/introduction
Build and install packages that extend a Neuron
A Neuron package can add .NET modules, HTTP resources, MCP servers, Script functions, schemas, Markdown pages, JavaScript, and static assets.
Start with the [package quickstart](/neuron-development/quickstart). It uses public NuGet packages and does not require the Neuro-Ledger or IoTBroker source repositories.
## Choose a package type
| Package | Use it for | Restart required |
| ---------------- | --------------------------------------------------------------------- | ---------------- |
| Content package | Markdown, Script, JavaScript, schemas, and static files | No |
| Assembly package | C# modules, HTTP resources, MCP servers, codecs, and runtime services | Yes |
## Build against published packages
You can compile modules against packages published on NuGet. The package versions must match the installed Neuron runtime. The Neuron installation supplies the utilities used to turn a manifest into an installable package.
Do not copy DLLs from an unrelated Neuron build or guess package versions. A project can compile successfully and still fail to load when its runtime dependencies do not match the target Neuron.
## Build a package in this order
1. [Build your first package](/neuron-development/quickstart).
2. Define the files in the [package manifest](/neuron-development/package-architecture).
3. Add behavior using the [module lifecycle](/neuron-development/module-lifecycle).
4. [Test and debug](/neuron-development/testing-and-debugging).
5. [Build](/neuron-development/building-packages) and [install](/neuron-development/installing-packages) a distributable package.
# Module lifecycle
Source: https://docs.neuro-tech.io/neuron-development/module-lifecycle
Start and stop Neuron extensions safely through runtime inventory
Assembly packages expose long-lived behavior through `Waher.Runtime.Inventory.IModule`. Runtime inventory finds concrete implementations, creates them, calls `Start()`, and later calls `Stop()` during shutdown.
```csharp theme={null}
public interface IModule
{
Task Start();
Task Stop();
}
```
Use `IConfigurableModule` when the assembly also contributes setup pages:
```csharp theme={null}
public interface IConfigurableModule : IModule
{
Task GetConfigurablePages();
}
```
## Ownership rule
Every resource acquired or registered in `Start()` must have one clear owner and a matching release in `Stop()`. Store the exact instance/delegate; many unregister operations require identity equality.
```csharp theme={null}
[Singleton]
public sealed class ExampleModule : IModule
{
private QueueWebService? endpoint;
public Task Start()
{
HttpAuthenticationScheme[] schemes = HttpModule.GetAuthenticationSchemes();
this.endpoint = new QueueWebService("/ExampleQueues", schemes);
Gateway.HttpServer?.Register(this.endpoint);
return Task.CompletedTask;
}
public Task Stop()
{
if (this.endpoint is not null && Gateway.HttpServer is not null)
Gateway.HttpServer.Unregister(this.endpoint);
this.endpoint = null;
return Task.CompletedTask;
}
}
```
The example reuses the queue resource to show the lifecycle. A real package normally registers its own `HttpResource` or a controller router.
## Start safely
1. Validate configuration without logging secrets.
2. Create dependencies that do not publish work.
3. Register routes, stanza handlers, event sinks, and runtime services.
4. Start background loops last.
5. If any step fails, unwind already-created resources before rethrowing.
Do not use fire-and-forget tasks from `Start()`. Keep a cancellation token source and task, surface unexpected termination to the event log, and await the task during `Stop()`.
## Stop safely
1. Stop accepting new work or unregister ingress.
2. Cancel background loops.
3. Await in-flight tasks with a bounded policy.
4. Flush durable state and queues.
5. Unregister handlers, routes, event sinks, and timers.
6. Dispose owned dependencies.
Make `Stop()` safe after a partial start and safe if called once more. Do not dispose gateway-owned singletons such as `Gateway.HttpServer` or the global database provider.
## Runtime inventory
`Types.GetTypesImplementingInterface(...)` and `Types.Instantiate(...)` are used throughout Neuron to discover endpoints, handlers, Script functions, MCP tools, converters, and other extensions. Consequences:
* avoid two discoverable implementations claiming the same route/name/namespace;
* make discovered types concrete and constructible according to the consuming subsystem;
* use `[Singleton]` only when one shared instance is correct;
* expect adding an assembly to change inventory results globally;
* test startup with the same assembly set as production.
## Failure visibility
Log the module/type name and stable event ID. Throwing from `Start()` should prevent a falsely healthy deployment; swallowing registration failures can leave only part of a package active.
# Package manifest
Source: https://docs.neuro-tech.io/neuron-development/package-architecture
Describe the assemblies and content installed by a Neuron package
A package starts with a manifest. The manifest is XML in the ModuleManifest namespace and lists every installed file.
## Minimal assembly manifest
```xml theme={null}
```
Assembly paths are relative to the manifest. Assembly packages require a Neuron restart before the runtime can discover new module types.
## Minimal content manifest
```xml theme={null}
```
Content under Root is installed into the Neuron web-content tree. Only files named in the manifest are included.
## Keep the output self-contained
Place the manifest beside the files it references, or copy it to the build output:
```xml theme={null}
```
## Rules
* Use the exact ModuleManifest namespace.
* List every file that must be installed.
* Do not include runtime DLLs already supplied by the target Neuron.
* Add third-party dependencies only when the Neuron does not supply them.
* Test installation against the same Neuron build used for dependency selection.
* Treat filename casing as significant for deployments on Linux.
Continue with [Build packages](/neuron-development/building-packages).
# Persistence, queues, and events
Source: https://docs.neuro-tech.io/neuron-development/persistence-and-events
Store typed objects, index queries, publish structured events, and make background work durable
Neuron code targets the `Waher.Persistence.Database` abstraction. The configured provider can be the files database, lightweight files database, an external provider, or a test provider; application code should not depend on one storage engine's files.
## Define a persisted model
```csharp theme={null}
using Waher.Persistence.Attributes;
[CollectionName("ExampleJobs")]
[Index("State", "Created")]
public sealed class ExampleJob
{
[ObjectId]
public string ObjectId { get; set; } = string.Empty;
public string State { get; set; } = "Pending";
public DateTime Created { get; set; } = DateTime.UtcNow;
[DefaultValueNull]
public string? LastError { get; set; }
}
```
Index fields in the same order used by high-volume filters and sorts. Changing attributes changes persistence semantics, so test old records, missing properties, and migrations—not only new inserts.
## CRUD
```csharp theme={null}
await Database.Insert(job);
ExampleJob? pending = await Database.FindFirstIgnoreRest(
new FilterFieldEqualTo(nameof(ExampleJob.State), "Pending"));
if (pending is not null)
{
pending.State = "Running";
await Database.Update(pending);
}
```
Common filter classes include equality, range comparisons, regular expressions, logical `FilterAnd`/`FilterOr`, and paging/sort arguments. Use bounded reads. `FindFirstDeleteRest` deliberately deletes duplicate matches and should only be used when uniqueness and cleanup are intended.
## Consistency
The generic object API does not turn an arbitrary read-modify-write sequence into a cross-object transaction. Design with:
* unique business identifiers and idempotent commands;
* explicit state transitions;
* optimistic conflict checks where competing writers are possible;
* persisted intent/outbox records before invoking external services;
* reconciliation jobs for interrupted work.
Use `Waher.Runtime.Transactions` only after understanding the participating resources and recovery behavior.
## Persistent queues
`DatabaseQueue`/`IPersistedQueue` provide durable FIFO work, and the `/Queues` service exposes authorized HTTP access when installed. Use distinct queue names per contract and environment. A consumer should:
1. dequeue a bounded batch with a timeout;
2. validate and deserialize defensively;
3. apply an idempotency key before side effects;
4. record success or a retry/dead-letter decision;
5. expose depth, age, throughput, and failures as counters/events.
Do not use an in-memory `Task.Run` loop for work that must survive restart.
## Structured event log
Use `Waher.Events.Log` for operational events. Levels range from debug and informational through notice, warning, error, critical, alert, and emergency. Include stable object/actor/facility/event identifiers and structured tags so operators and the Event Log MCP server can search them.
```csharp theme={null}
Log.Informational(
"Example job completed.",
job.ObjectId,
"ExampleWorker",
"Example.Job.Completed");
```
Never log passwords, bearer tokens, private keys, verification codes, raw identity documents, or unredacted contract attachments. Event sinks can forward logs to files, XMPP, MQTT, queues, statistics, or custom destinations; registering a sink creates a data-egress path that needs its own security review.
# Build your first package
Source: https://docs.neuro-tech.io/neuron-development/quickstart
Compile and install a minimal Neuron module using NuGet
This guide creates an assembly package that writes an event when the Neuron starts.
## Prerequisites
* A local [Neuron installation](/operations/install) that you can stop and start.
* The .NET SDK.
* PowerShell.
* The Neuron application folder, program-data folder, and Windows service name.
The sample below was build-tested with Waher.IoTGateway 3.10.2. Use the version that matches your installed Neuron when they differ.
## 1. Create the project
```powershell theme={null}
mkdir HelloNeuron
cd HelloNeuron
dotnet new classlib --framework netstandard2.1
dotnet add package Waher.IoTGateway --version 3.10.2
```
The package targets .NET Standard 2.1 because the public runtime package targets that framework.
## 2. Configure the project
Replace HelloNeuron.csproj with:
```xml theme={null}
netstandard2.1
enable
```
## 3. Add a module
Delete Class1.cs and create HelloNeuronModule.cs:
```csharp theme={null}
using System.Threading.Tasks;
using Waher.Events;
using Waher.Runtime.Inventory;
namespace HelloNeuron
{
public sealed class HelloNeuronModule : IModule
{
public Task Start()
{
Log.Informational("HelloNeuron started.");
return Task.CompletedTask;
}
public Task Stop()
{
Log.Informational("HelloNeuron stopped.");
return Task.CompletedTask;
}
}
}
```
The runtime discovers concrete IModule implementations and calls Start after loading the assembly.
## 4. Add the manifest
Create HelloNeuron.manifest next to the project file:
```xml theme={null}
```
The manifest lists every assembly and content file installed by the package.
## 5. Build
```powershell theme={null}
dotnet build --configuration Release
```
Verify that the output folder contains:
```text theme={null}
bin/Release/netstandard2.1/
|-- HelloNeuron.dll
`-- HelloNeuron.manifest
```
Warnings about a transitive dependency resolving to a newer patch version come from the published runtime package. Review them against the target Neuron instead of suppressing all NuGet warnings.
## 6. Install in the local Neuron
Set these values from your installation:
```powershell theme={null}
$NeuronService = ""
$NeuronApp = ""
$NeuronData = ""
$Installer = Join-Path $NeuronApp "InstallUtility\Waher.Utility.Install.exe"
$Server = Join-Path $NeuronApp "Waher.IoTGateway.Svc.exe"
$Manifest = Resolve-Path ".\bin\Release\netstandard2.1\HelloNeuron.manifest"
```
Stop the service, install from the manifest, and restart:
```powershell theme={null}
Stop-Service -Name $NeuronService
& $Installer -m $Manifest -s $Server -d $NeuronData -v
Start-Service -Name $NeuronService
```
The executable and data paths can differ between installer versions. Read the Windows service PathName and the Neuron configuration instead of copying paths from another machine.
## 7. Verify
Open the Neuron event log and search for:
```text theme={null}
HelloNeuron started.
```
If the event is present, the runtime found the assembly, created the module, and called Start.
## Next step
* Add an [HTTP resource or content handler](/neuron-development/http-content-and-protocols).
* Add [persistence and structured events](/neuron-development/persistence-and-events).
* Build a [custom MCP server](/mcp/build-a-server).
* Create a signed package for distribution with [Build packages](/neuron-development/building-packages).
# Release and deploy a package
Source: https://docs.neuro-tech.io/neuron-development/runtime-deployment
Move a tested package from development to a managed Neuron
## Before release
* Record the target Neuron build.
* Pin compatible NuGet versions.
* Install the package in a disposable Neuron.
* Test a restart, upgrade, and rollback.
* Sign with the approved publisher key.
* Keep a backup of the previous package.
## Content and assembly releases
| Package | Restart | Review |
| ------------ | ---------- | ----------------------------------------------------------- |
| Content only | Usually no | Check paths, active content, and browser behavior |
| Assembly | Yes | Review code, dependencies, privileges, and startup behavior |
## Separate package and deployment responsibilities
Package creation and package installation are separate responsibilities. A developer can submit a signed artifact; a Neuron administrator decides whether that publisher and package are trusted.
Do not give an application account or AI agent permission to install executable assemblies on a shared or production Neuron.
## Verify after deployment
1. Confirm the package version shown by the Neuron.
2. Inspect startup events and exceptions.
3. Exercise one read operation and one intended write operation.
4. Restart once and repeat the check.
5. Confirm monitoring and backups still work.
# Test and debug a package
Source: https://docs.neuro-tech.io/neuron-development/testing-and-debugging
Find build, installation, and startup failures
## Test before installation
```powershell theme={null}
dotnet build --configuration Release
dotnet test --configuration Release
```
Keep parsing, validation, policy, and state-transition logic independent of the Neuron where possible.
## Smoke-test the package
1. Install it in a disposable Neuron.
2. Restart when it contains assemblies.
3. Confirm each module starts.
4. Call one public endpoint or open one content page.
5. Stop the Neuron and confirm the module releases timers, ports, and files.
## If the module is not loaded
* Confirm the DLL is listed in the manifest.
* Confirm the installed DLL is in the Neuron application folder.
* Check that its target framework and dependency versions match the Neuron.
* Search startup exceptions for missing assemblies or type-load errors.
* Confirm the module is concrete and implements IModule.
## If an endpoint is missing
* Check that registration happens from Start.
* Check for duplicate paths.
* Confirm Start completed without an exception.
* Inspect the Neuron route list or discovery output before debugging request logic.
## If an upgrade fails
Restore the previous tested package or backup before making additional changes. Keep the first exception and exact package version; repeated restart attempts often hide the original failure.
# Configure a Neuron
Source: https://docs.neuro-tech.io/operations/configuration
Choose between the setup wizard, environment variables, and Gateway.config
A Neuron can be configured interactively, through environment variables, and through the runtime's `Gateway.config` module graph. Use each mechanism for the layer it owns.
| Mechanism | Best for | Change behavior |
| --------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| First-run pages | Initial operator decisions and generated secrets | Stored in the configured persistence layer or program data |
| Environment variables | Repeatable deployment inputs and secret injection | Read during setup/startup; names are module-specific |
| `Gateway.config` | Runtime modules, event sinks, protocol extensions, web behavior | Requires validation and usually a restart |
| Admin UI | Supported day-to-day configuration | Applies validation and persists through the owning module |
## Environment variables
Environment variables allow the first-run sequence to be automated. The available variables come from the installed modules, so the definitive set for an installation is the set exposed by that build.
Common groups include:
* database provider, folder, encryption and connection settings;
* backup schedule and retention;
* domain, ports, certificates and Internet-gateway settings;
* XMPP account, federation and API-key settings;
* administrator and user provisioning;
* legal-identity, ledger, mail, theme and notification settings.
Do not put passwords, API secrets, private keys, certificate passwords, or JWT secrets in a committed `.env` file. Inject them from a secret store and restrict access to the service process.
Use an installation-specific environment template as a checklist. Unknown variables can be ignored silently by some deployment wrappers, so verify the resulting state after startup.
## Edit Gateway.config safely
`Gateway.config` declares runtime modules and their configuration. Packages can add new elements, including event sinks, web resources, persistence providers, protocol handlers, and scheduled jobs.
1. Locate the active program-data folder from the running service.
2. Make a recoverable copy of `Gateway.config`.
3. Edit the file as UTF-8 XML.
4. Validate it against the schema shipped with the same build.
5. Restart the service.
6. Inspect the event log for module-load or XML-validation errors.
Avoid copying a configuration file between different Neuron versions without reviewing module and schema changes.
## Domain-specific web configuration
The web server can serve different content and policy for different domains. Use domain-specific configuration when a single Neuron terminates multiple host names. Keep authentication callbacks, OAuth redirect URIs, CSP, CORS, and canonical links aligned with the selected domain.
## Custom HTTP headers
Headers such as CORS, CSP, cache control, and security headers can be attached to web resources through the configured web-resource layer. Apply them to the narrowest resource scope possible. In particular:
* never combine `Access-Control-Allow-Origin: *` with credentialed browser access;
* keep API responses non-cacheable when they contain account or identity data;
* test CSP changes against Markdown-generated pages and package assets;
* do not override transport-security headers on plain HTTP.
## Configuration drift check
After each deployment, record:
```text theme={null}
Neuron build
Installed packages and versions
Configuration source revision
Certificate subject and expiry
Database provider
Enabled public listeners
Backup destination and last successful backup
```
This small manifest makes incident response and reproducible staging environments substantially easier.
# Complete first-run setup
Source: https://docs.neuro-tech.io/operations/first-run
Configure persistence, networking, identity, backups, and services
The first-run wizard is available only from `localhost`. Complete it from the Neuron host before exposing the service publicly.
## Configuration sequence
Select the encrypted internal object database for a single-node deployment, or a supported external database such as MongoDB when multiple runtime nodes must share data. Record where database encryption keys are stored.
Read the personal-data disclosure and confirm that the deployment's purpose, retention, and access policies match it. This is an operational decision, not a checkbox to automate blindly.
Restore an existing backup if this server replaces another instance. Otherwise enable automatic backups, choose retention, and place copies outside the server's program-data disk.
If the host is behind a gateway, configure port forwarding for the protocols you use. Prefer explicit mappings and verify them from outside the local network.
Set the canonical domain name. Configure address records and, when applicable, XMPP SRV records, mail MX/SPF records, and certificate validation records.
Enable client-to-server and server-to-server listeners as required. Federation needs public DNS, a valid certificate, and reachable port `5269`.
Apply for or import the Legal Identity used by the Neuron. This identity anchors signed contracts and service assertions made by the server.
Configure ledger participation, roster defaults, mail relay, visual theme, and operator notifications only where the deployment needs them.
## DNS verification
At minimum, the canonical host name must resolve to the public address that reaches the Neuron. For XMPP federation, publish SRV records for the services you expose. A typical shape is:
```dns theme={null}
_xmpp-client._tcp.example.com. 3600 IN SRV 0 5 5222 neuron.example.com.
_xmpp-server._tcp.example.com. 3600 IN SRV 0 5 5269 neuron.example.com.
```
Use your DNS provider's syntax and include the final dot only when its UI expects a fully qualified name.
## Verify from outside
Local success does not prove that NAT, DNS, certificates, or firewall rules work externally. From a separate network, verify:
```bash theme={null}
curl --fail --show-error https://neuron.example.com/
```
Also test XMPP federation if it is enabled. The administrative **Ports** view shows local listeners; it cannot confirm an Internet path through an upstream firewall.
## Secure the administration surface
1. Create a named administrator account.
2. Store its credentials in an approved password manager.
3. Restrict administration routes with the Web Application Firewall.
4. Create narrower roles for operators, support staff, MCP clients, and applications.
5. Confirm that a non-administrator account cannot reach administrative pages.
## Before going live
* Trigger one backup and restore it in a non-production environment.
* Confirm certificate expiration and renewal behavior.
* Send a test operator notification.
* Inspect event and exception logs.
* Record the package versions and configuration source used for the deployment.
# Install a Neuron
Source: https://docs.neuro-tech.io/operations/install
Prepare a Windows host and install the Neuron service
After this guide, the Neuron service is installed and its local first-run page opens in a browser.
## Prerequisites
* A supported 64-bit Windows host with administrator access.
* A DNS name for production use.
* Permission to bind the HTTP, HTTPS, XMPP, and any SMTP ports you plan to expose.
* A backup location outside the Neuron program-data directory.
The Neuron includes its own web server. Remove or reconfigure IIS and any other service already bound to ports `80` or `443`.
## Plan firewall rules
Open only the services you use.
| Port | Protocol | Purpose |
| ---------: | --------------- | ------------------------------------------------- |
| `80/TCP` | HTTP | Certificate challenges and optional HTTP redirect |
| `443/TCP` | HTTPS | Web UI, HTTP APIs, OAuth, and MCP |
| `5222/TCP` | XMPP C2S | Client-to-server XMPP |
| `5269/TCP` | XMPP S2S | Federation between XMPP domains |
| `25/TCP` | SMTP | Direct server-to-server mail, when enabled |
| `587/TCP` | SMTP submission | Authenticated mail submission, when enabled |
| `1080/TCP` | SOCKS5 | Optional proxy service |
RDP (`3389/TCP`) is an operating-system administration port, not a Neuron dependency. If used, restrict it to trusted source addresses or a private administration network.
## Run the installer
1. Download `NeuronSetup.exe` from your organization's approved distribution channel.
2. Run the installer as the interactive user. Do not use **Run as administrator** unless the release instructions explicitly require it; installing with the wrong identity can leave database keys unreadable by the service account and can prevent self-updates.
3. Accept the licence and select the target instance.
4. Wait for the service to enter the running state.
5. Open `http://localhost/` on the host.
On first start the runtime creates encryption keys for local database files. Key generation can make the service remain in **Starting** for a while. Check service state and CPU activity before terminating it.
## Verify the installation
```powershell theme={null}
Get-Service | Where-Object { $_.DisplayName -match 'Neuron|IoT Gateway' }
```
Then request the local landing page:
```powershell theme={null}
Invoke-WebRequest http://localhost/ -UseBasicParsing
```
A successful HTTP response proves the web listener is available. It does not mean the first-run configuration is complete.
## Files and service state
The Windows installer normally separates immutable program files from mutable program data. The program-data folder contains configuration, databases, logs, package state, generated keys, and hosted content. Its exact location is selected by the installer and can differ between installations; verify it from the service configuration before scripting paths.
## Next step
Continue with [Complete first-run setup](/operations/first-run).
# Observe a Neuron
Source: https://docs.neuro-tech.io/operations/observability
Use event logs, exception logs, sniffers, notifications, and queues
Start every investigation with the structured event log. Add protocol sniffers only when the event data is insufficient.
## Event levels
| Level | Use |
| ------------- | ----------------------------------------------- |
| Debug | Developer diagnostics; normally high volume |
| Informational | Normal operational activity |
| Notice | A significant condition or configuration change |
| Warning | A condition that can become an error |
| Error | An expected operation failed |
| Critical | An unexpected failure that can escalate |
| Alert | Immediate operator action is required |
| Emergency | The system is or is becoming unusable |
Use stable event IDs for machine processing. Add actor, object, facility, module, and structured tags rather than embedding all context in the message.
## Exception logs
Exception logs preserve stack traces and nested exceptions that may be abbreviated in the event view. Correlate them with the event timestamp, actor, resource, and request ID. Remove secrets and unnecessary personal data before sharing a trace.
## Protocol sniffers
Sniffers can capture HTTP, XMPP client-to-server, XMPP server-to-server, SMTP, ledger, and other protocol traffic provided by installed modules.
A sniffer can capture credentials, tokens, message bodies, identity data, and contract content. Limit its duration and audience, and delete captures according to your incident-data policy.
## Operator notifications
Notification settings determine which events are only logged and which are pushed to operators. Configure high-signal events such as account or API-key creation, recovery requests, legal-identity review, automatic approval/rejection, and contract proposals. Avoid routing high-volume informational events as immediate alerts.
## Queue event sink
An `EventQueue` sink can persist events in an encrypted FIFO queue so producers do not block on downstream processing. Configure a queue name, retention period, and sink ID in `Gateway.config` or the gateway configuration source. Consumers can dequeue locally or use the Queue API.
Queue design rules:
* make consumers idempotent;
* persist the last processed business identifier, not only an in-memory offset;
* choose retention longer than the maximum expected outage;
* monitor queue depth and oldest-item age;
* send poison events to an explicit dead-letter workflow.
## Investigation order
1. Confirm service state and current build.
2. Search events around the first failure.
3. Open the linked exception, if any.
4. Check package/module load events after the last restart.
5. Inspect listener and connection state.
6. Enable the narrowest relevant sniffer for a short reproduction.
7. Disable the sniffer and preserve only the evidence required.
# Operate a Neuron
Source: https://docs.neuro-tech.io/operations/overview
Install, configure, secure, update, and troubleshoot a Neuron server
A **Neuron** is the server runtime at the center of the Neuro platform. It combines an HTTPS server, an XMPP broker, identity and contract services, package hosting, persistence, scripting, and operational tooling in one extensible process.
This section is for operators and developers who run a Neuron. It covers installation, initial setup, access control, monitoring, updates, and troubleshooting.
## Choose your task
Prepare a Windows host, open the required ports, and run the installer.
Configure persistence, backups, networking, XMPP, and the server identity.
Use environment variables and `Gateway.config` for repeatable deployments.
Create users and roles, then grant the minimum privileges required.
Extend a Neuron with signed content and assembly packages.
Work from event logs, protocol sniffers, exception reports, and service state.
## Runtime layers
| Layer | Responsibility |
| --------------- | ------------------------------------------------------------------------------ |
| Host | Windows service lifecycle, process identity, firewall, certificates, files |
| Gateway runtime | Module discovery, configuration, scheduling, persistence, events |
| Protocols | HTTP/HTTPS, XMPP client-to-server and server-to-server, SMTP, optional proxies |
| Neuro services | Accounts, legal identities, contracts, wallet, tokens, ledger, Agent API |
| Extensions | Signed packages containing web content, scripts, schemas, or .NET assemblies |
Treat the Neuron program-data folder, database keys, TLS keys, API secrets, package keys, and JWT secrets as production credentials. Back them up securely and never commit them to source control.
## Production checklist
* Use a stable domain name with correct DNS records.
* Enable HTTPS and validate renewal before exposing the server.
* Restrict administrative resources and RDP to trusted networks.
* Configure automatic backups and test restoration.
* Create role-specific accounts instead of sharing an administrator account.
* Review the event log and exception log after every deployment.
* Keep package signing keys separate from the Neuron host.
* Enable protocol sniffers only while diagnosing a problem; captures can contain sensitive data.
## Related developer guides
* [Build a Neuron package](/neuron-development/building-packages)
* [Connect an MCP client](/mcp/connect-a-client)
* [Use the Script engine](/script/quickstart)
* [Integrate with the Agent API](/neuron-api/quickstart)
# Query runtime counters
Source: https://docs.neuro-tech.io/operations/runtime-counters
Read live counters, compare snapshots, and build operational reports
Runtime counters are maintained in memory and periodically persisted. Use the Script counter functions for current values; querying the database alone can return an older value.
## Read counters
Each persisted `RuntimeCounter` has `ObjectId`, `Key`, and `Counter`. List keys and fetch their live value:
```text theme={null}
SELECT
Key,
GetCounter(Key) AS Value
FROM RuntimeCounter
ORDER BY Key
```
If you query the collection name `RuntimeCounters`, quote it because the same name is also a .NET namespace:
```text theme={null}
SELECT count(*) FROM "RuntimeCounters"
```
Useful functions include `GetCounter`, `GetCounters`, `IncCounter`, `DecCounter`, and the counter flush function available in the installed build.
## Compare snapshots
Create a dictionary keyed by counter name:
```text theme={null}
Sample1:={};
foreach Counter in (SELECT Key FROM RuntimeCounter) do
Sample1[Counter]:=GetCounter(Counter);
```
Take the second sample later and subtract the dictionaries:
```text theme={null}
Sample2:={};
foreach Counter in (SELECT Key FROM RuntimeCounter) do
Sample2[Counter]:=GetCounter(Counter);
Diff:=Sample2-Sample1;
[P in [foreach P in Diff:P]:P.Value!=0]T
```
Dictionary subtraction treats a missing key as the additive zero value, making it suitable when counters appear between samples.
## Counter reports
The administrative **Sources & Nodes** view can expose file-based reports for labelled snapshots and comparisons. Standard reports include general counter comparison and a billable-counter view.
Typical business counters include account creation, remote login, legal-identity states, contract/template states, and KYC provider operations. Treat the exact keys as versioned runtime output: discover them from the server instead of hard-coding an exhaustive list.
## Reporting guidance
* Record snapshot time, Neuron identity, build, and counter prefix.
* Use monotonically increasing counters for rates by comparing two labelled snapshots.
* Expect resets after database restoration or deliberate counter maintenance.
* Do not use counters as a financial ledger; use auditable domain events for settlement.
* Alert on rates and trends, not a single cumulative value.
See [Reports and automation](/script/reports-and-automation) to turn these queries into reusable operator reports.
# Install and update software packages
Source: https://docs.neuro-tech.io/operations/software-packages
Verify, install, distribute, update, and remove signed Neuron packages
Neuron packages distribute web content, scripts, schemas, configuration, and .NET assemblies. Content-only packages can normally be applied without a runtime restart; assembly packages require a restart so the runtime can load the new code.
## Package artifacts
| Artifact | Purpose |
| ---------------- | ----------------------------------------------------------- |
| `.package` | Encrypted package payload and manifest-listed files |
| `.signature` | Provider signature over the package |
| Installation key | Provider public key plus the package decryption key |
| `.manifest` | Build-time list of included files and installation metadata |
An installation key includes secret key material. Transfer and store it as a credential. The signature proves the provider; it does not make an untrusted package safe to execute.
## Install from the administration UI
1. Open the Neuron's **Software → Packages** page.
2. Upload the `.package` and matching `.signature` files, or choose an available package distributed by the parent Neuron.
3. Enter the installation key received through a trusted channel.
4. Review the provider identity, package name, and version.
5. Install the package.
6. If it contains assemblies, wait for the controlled restart.
7. Inspect the event and exception logs, then exercise the package's health check.
Uploading a package to a Neuron can propagate it to child Neurons in the configured software-distribution tree. Availability does not necessarily mean automatic installation.
## Update a package
Upload the new signed version. An operator can then approve the update or use chat administration:
```text theme={null}
upgrade PACKAGE_NAME.package
```
The `nobackup` form skips the pre-upgrade backup:
```text theme={null}
upgrade nobackup PACKAGE_NAME.package
```
Use it only when another verified recovery point exists.
## Command-line installation
For offline or automated installation, stop the Neuron and run the `Waher.Utility.Install` version that matches the target runtime:
```powershell theme={null}
Waher.Utility.Install.exe `
-d "" `
-s "" `
-p "" `
-k "" `
-v
```
Do not guess program-data or executable paths; multiple Neuron instances can be installed on one host.
## Verify and roll back
* Confirm the package version in the Installed list.
* Confirm required web resources and modules registered successfully.
* Search the event log by package/module name.
* Run one functional request through the new capability.
* To roll back, use the package's supported uninstall or install the previously approved version. Restoring arbitrary files by hand can leave persistence migrations or module state inconsistent.
To create packages, see [Building packages](/neuron-development/building-packages).
# Troubleshoot a Neuron
Source: https://docs.neuro-tech.io/operations/troubleshooting
Diagnose startup, TLS, network, database, package, and authorization failures
Use this sequence before changing configuration. It preserves evidence and prevents a secondary failure from hiding the first one.
## Triage sequence
1. Record the exact time, URL or JID, account, operation, and observed response.
2. Check Windows service state and process uptime.
3. Search the Neuron event log at that time.
4. Open any associated exception entry.
5. Confirm the active build and installed package versions.
6. Reproduce once with the narrowest applicable protocol sniffer.
7. Stop the sniffer and redact secrets before sharing evidence.
## Service does not start
Check, in order:
* another process already owns a required port;
* the service identity can read program files and program-data keys;
* `Gateway.config` is well-formed and matches the installed modules;
* a newly installed assembly package loads on the current runtime;
* the database path or external database is reachable;
* disk space is available for database journals, logs, and package extraction.
Do not repeatedly reinstall over an existing data folder. First copy the event/exception logs and confirm where encryption keys are stored.
## HTTPS or certificate failure
* Resolve the configured host name from both inside and outside the network.
* Confirm ports `80`/`443` reach this instance.
* Check certificate subject alternative names and expiry.
* Verify the service can read the private key.
* Check whether an upstream proxy terminates TLS and which forwarded headers it sets.
* For mTLS, verify the client actually sends a certificate and that the chain and intended usages are accepted.
## `401 Unauthorized` versus `403 Forbidden`
`401` means the request lacks acceptable authentication or its credential is invalid/expired. `403` means the server recognized the caller but the caller lacks authorization for the resource or object.
For `403`, do not retry the same token in a loop. Check:
* assigned roles and exact privilege;
* ownership or account-specific resource path;
* OAuth scopes granted into the token;
* WAF rules and source-address restrictions;
* object-level authorization for identity, contract, vault, or file resources.
## Package update failure
* Verify `.package` and `.signature` belong to the same build.
* Confirm the installation key uses the expected provider public key and decryption key.
* Inspect pre-update backup events.
* Check module-load exceptions after restart.
* Roll back through the package manager or restore a verified backup; do not mix individual DLLs from different package versions.
## Database keyset or decryption errors
These often indicate the service is running under a different identity, the key container permissions changed, or program data came from another host without its keys. Stop writes, take a file-level copy, record the service identity, and use the key recovery/migration procedure for that storage provider and Neuron build.
## Evidence bundle
Provide support with:
```text theme={null}
UTC time range
Neuron build and OS
Installed/changed package versions
Sanitized request and response
Relevant event IDs
Exception stack trace
Listener/DNS/certificate results
Minimal sniffer excerpt, if required
Recent configuration change
```
# Manage users, roles, and privileges
Source: https://docs.neuro-tech.io/operations/users-and-roles
Apply least-privilege access control to administrators, applications, and MCP clients
Neuron authorization is privilege-based. A **role** collects privileges; a user or XMPP account receives the union of privileges from its assigned roles.
## Account types
| Account | Used for |
| ------------------- | --------------------------------------------------------------- |
| Administrative user | Browser administration and protected HTTP resources |
| XMPP account | Federated messaging, service identities, and clients |
| OAuth client | Standards-based authorization to HTTP resources and MCP servers |
| Agent API account | Application-level Agent API sessions and domain services |
Do not assume these account types are interchangeable. A deployment can map an OAuth registration to an XMPP account internally, but access is still determined by the roles and privileges assigned to that identity.
## Create a least-privilege role
1. Open **Administration → Users and Roles → Roles**.
2. Create a role named for the job, not for a person, such as `McpFileReader` or `SupportEventViewer`.
3. Add only the privileges required by that job.
4. Assign the role to a test account.
5. verify both an allowed action and a denied action.
Privilege names are hierarchical. Granting a broad parent pattern can include future child privileges, so prefer explicit leaves for machine identities.
## OAuth scopes and privileges
OAuth scopes are translated to Neuron privileges with the prefix `OAUTH.Scope.`; colons in a scope become periods. For example, the MCP scope root `MCP:Files` maps into the `OAUTH.Scope.MCP.Files` privilege hierarchy.
Dynamic OAuth clients and XMPP-backed OAuth clients have no useful privileges by default. Registration establishes identity, not authorization.
## Separate human and machine access
* Give each integration its own account or OAuth client.
* Never share the main administrator credential with a service.
* Rotate a compromised client without affecting unrelated applications.
* Use short-lived bearer tokens and protect refresh tokens.
* Disable an account before deleting it when investigating an incident.
* Log actor, object, facility, module, and event ID for privileged automation.
## Recover administrative access
If all administrator access is lost, stop and identify the active database and program-data folder before editing anything. Recovery procedures are storage-provider and build specific. Make a backup first, then use the recovery utility or documented database procedure shipped with the same build. Do not create a second fresh configuration over the existing data directory; it can replace keys needed to decrypt the database.
## Audit checklist
* Every account has an owner and purpose.
* Machine accounts use narrowly scoped roles.
* Former staff and retired services are disabled.
* OAuth redirect URIs are exact and still controlled.
* Privilege changes produce auditable events.
* Administrative pages are also restricted at the network/WAF layer.
# Host web content and services
Source: https://docs.neuro-tech.io/operations/web-hosting
Serve Markdown, static assets, APIs, and reverse-proxied applications from a Neuron
The Neuron web server serves content directly from the program-data `Root` tree and from installed packages. Markdown is rendered dynamically, which makes documentation, administration pages, forms, scripts, and APIs part of the same extensible web runtime.
## Publish static or Markdown content
1. Build a content-only package containing the files under their intended web-root paths.
2. Include every shipped file in the package manifest.
3. Use relative links for files that move together and root-relative links for stable site routes.
4. Install the package in a test Neuron.
5. Verify HTML rendering, JavaScript, content types, cache headers, and access control.
Prefer packages over manual edits in `ProgramData`. Package installation is repeatable, signed, and reversible.
## Host a single-page application
Build the application with the correct base path, then package the compiled output. For a subdirectory such as `/portal/`, configure the frontend router and asset prefix for `/portal/` before building. Add a server fallback only for client-side routes; do not redirect missing API paths to `index.html`.
## Domain-specific roots
A Neuron can distinguish requests by host name. Use this to isolate brands or applications while sharing a runtime. Each domain still needs its own DNS, TLS coverage, OAuth redirect URIs, and security policy.
## Reverse proxy
Use a reverse proxy resource when an upstream application must appear under the Neuron's domain. Preserve the original host/path intentionally, set forwarding headers once, and define whether authentication happens at the Neuron, upstream, or both.
Security rules:
* allow only configured upstream origins;
* never turn the proxy into an unauthenticated arbitrary-URL relay;
* bound request and response sizes;
* strip hop-by-hop headers;
* decide how cookies, redirects, WebSockets, and client certificates are handled;
* log the authenticated actor and upstream target.
## Generic HTTP proxy
Recent Neuron builds can expose an authenticated `/HttpProxy` resource for controlled access to Internet content. It supports normal web authentication, sessions, JWT bearer tokens, and mTLS where configured. Treat it as a high-risk capability: restrict it with roles and the WAF, and audit target hosts.
## Content generation
Markdown pages can include Script-backed dynamic sections and can be transformed to HTML, JavaScript, images, and PDF by installed renderer modules. Keep expensive generation behind caching or a job queue, and validate untrusted input before passing it to a renderer.
See [Web and content scripting](/script/web-and-content) for dynamic pages and [HTTP content and protocols](/neuron-development/http-content-and-protocols) for code-defined routes.
# Glossary
Source: https://docs.neuro-tech.io/overview/glossary
Key terms and concepts used across the Neuro platform
This page collects the most important terms used across the platform.
You do not need to understand every term before you begin, but having a shared vocabulary makes the rest of the documentation much easier to follow.
The core runtime and broker in the Neuro platform. It enables secure, federated interaction across domains and hosts higher-level capabilities such as identities, contracts, tokens, and ledger-backed services.
The distributed audit and persistence layer used by the platform. It is designed to support auditable, distributed systems without depending on a traditional blockchain model.
A trusted actor within a domain that validates identities, approves or governs important platform objects, and contributes trust to the network through signatures and policy. Often described as a digital equivalent of a notary.
The identity used to participate in the network as a connected actor or account. It identifies who is communicating at the platform level.
A stronger, cryptographically protected identity tied to a real legal actor such as a person or organization. Legal identities are used when trust, signatures, ownership, or compliance matter.
A structured digital agreement used in the platform. In Neuro, smart contracts combine human-readable and machine-readable content, support signatures and lifecycle rules, and are designed to work across domains.
A digital instrument tied to ownership, agreements, and traceable events. In the platform, tokens can represent NFTs, asset-backed instruments, rights, or other digital and cyber-physical assets.
The Neuro platform's token model for digital instruments and tokenized assets. Neuro-Features are created using smart contracts and can represent ownership, rights, or asset-backed structures.
A federated digital payment mechanism used in the broader platform model. It can be linked to contracts, tokens, and programmable payment flows.
A model where multiple domains manage their own infrastructure but still interoperate in a shared framework. Federation is a core part of how Neuro supports cross-domain interaction.
A distinct operating boundary in the federated network. Each domain can manage its own users, services, policies, and trust relationships.
A cryptographic proof attached to an identity, contract, or other platform object to verify integrity and authorship. Signatures are central to how Neuro establishes trust.
The part of a cryptographic key pair used to validate signatures or encrypted interactions.
The secret part of a cryptographic key pair used to create signatures. Custody depends on the integration: a direct XMPP client manages its private keys, while Agent API key operations use key material stored encrypted by the Neuron and invoked through the Agent interface.
A structured model for representing workflows as states and allowed transitions over time. In Neuro, state machines can be connected to contracts, tokens, and programmable payment logic.
Neuro's main HTTP API. The caller acts through a Neuron's Agent endpoint instead of connecting directly over XMPP while holding the corresponding private keys. The name is unrelated to artificial-intelligence agents.
The federated communication protocol underlying the Neuron's communication model. It provides the base for secure, cross-domain messaging and interaction.
The ability to inspect and verify what happened, who acted, and what was recorded. Auditability is one of the main reasons the platform uses Neuro-Ledger together with signatures and identities.
## Go deeper
See how the main components relate at runtime.
Choose an operations, API, Script, MCP, contract, or IoT guide.
# What is a Neuron?
Source: https://docs.neuro-tech.io/overview/what-is-the-neuron
The practical role of the Neuron server
A **Neuron** is the server you install and connect to when building on Neuro.
It provides:
* an HTTPS web interface and Agent API;
* accounts, roles, and OAuth;
* MCP servers for AI clients;
* legal identities and smart contracts;
* Neuro-Features and ledger-backed audit records;
* XMPP and IoT services;
* a package runtime for .NET modules, Script, and web content.
## How developers use it
```mermaid theme={null}
flowchart LR
App[App or service] --> API[Agent API]
Agent[AI client] --> MCP[MCP]
Device[Thing] --> IoT[IoT interfaces]
Package[.NET or content package] --> Runtime[Neuron runtime]
API --> Runtime
MCP --> Runtime
IoT --> Runtime
```
You normally work with one of those interfaces. You do not need the server source code to call the API, connect MCP, create contracts, or build against the public runtime packages.
## Local and remote Neurons
A local Neuron is useful for package development and administrative testing. A remote Neuron uses the same application interfaces, but its administrator controls accounts, roles, package installation, and network configuration.
## Next step
* [Install a Neuron](/operations/install)
* [Build your first package](/neuron-development/quickstart)
* [Connect with MCP](/mcp/quickstart)
# Accounts and Legal Identities
Source: https://docs.neuro-tech.io/platform/accounts-and-identities
Distinguish authentication accounts from reviewed identities used in trusted workflows
An **Account** establishes access to a Neuron. A **Legal Identity** represents an actor for workflows that require reviewed identity data, signatures, contract participation, or another stronger trust decision.
They are related, but they are not interchangeable.
| Object | Answers | Typical lifecycle |
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Account | “Which Neuron principal is authenticated?” | Created, contact details verified where required, authenticated, recovered or transferred |
| Legal Identity application | “Which identity is being submitted for review?” | Prepared, submitted with required attributes and attachments, reviewed |
| Legal Identity | “Which reviewed actor participates in this workflow?” | Returned with its current status and used according to the relying workflow's policy |
## Why the distinction matters
Logging in proves control of account credentials. It does not by itself prove that the account has a current Legal Identity or that a relying application should accept that identity for a particular purpose.
An application must state its own requirement explicitly:
```text theme={null}
Authenticated account only
or
Current Legal Identity required
or
Specific provider, review, role, or contract rule required
```
## Onboarding paths
| Situation | Start with |
| ------------------------------------- | --------------------------------------------------------------- |
| Trusted backend creates a new account | [User onboarding](/neuron-api/guides/user-onboarding) |
| Browser user creates an account | [Browser-based signup](/neuron-api/guides/browser-based-signup) |
| Existing Neuro user signs in | [Sign in with Neuro](/build/sign-in-with-neuro/overview) |
| Account applies for a Legal Identity | [Verified identity](/build/verified-identity/overview) |
## State applications must retain
Persist identifiers and status needed to resume the workflow. Do not use display names or email addresses as substitutes for returned account, application, key, or Legal Identity identifiers.
Identity review is asynchronous. The application must handle at least a pending outcome and a terminal approved or rejected outcome using the delivery or query mechanism supported by its Neuron.
## Keep account and identity data separate
Never put an account-creation API secret in browser or distributable mobile code. A browser onboarding flow can differ from normal Agent API JSON requests and may use hosted forms, redirects, and a session-token exchange; follow the dedicated guide instead of adapting backend examples.
## Reference
* [Accounts and onboarding](/neuron-api/api-reference/accounts-and-onboarding/overview)
* [Authentication and sessions](/neuron-api/api-reference/authentication-and-sessions/overview)
* [Legal Identities](/neuron-api/api-reference/legal-identities/overview)
# Platform architecture
Source: https://docs.neuro-tech.io/platform/architecture
How applications, Neurons, trust services, and the Neuro-Ledger fit together
Applications connect to a **Neuron**, the operator-hosted runtime that exposes Neuro capabilities. Choose an integration based on where your code runs and who manages credentials and private keys.
```text theme={null}
Application backend ── SDK or HTTPS Agent API ──┐
AI application ─────── MCP tools ───────────────┤
Direct client ──────── XMPP ────────────────────┤
↓
Neuron
│
Accounts, identities, contracts, features, wallets
│
↓
Neuro-Ledger
```
The diagram is a developer navigation model. It does not imply that every Neuron enables every capability or that every deployment shares one central API host.
## Choose where credentials are managed
| Caller | Recommended interface | What the caller manages |
| ---------------------- | ----------------------------------------------------- | --------------------------------------------------------------- |
| Backend service | Supported SDK, otherwise Agent API | Application credentials, sessions, and secure server-side state |
| Browser or mobile UI | Application backend plus a supported user-facing flow | User interaction; no embedded Agent API secret |
| AI application | Supported, scoped MCP tools | Tool selection and human approval rules |
| Direct protocol client | XMPP | Its connection and private keys |
| Neuron extension | Neuron package | Package lifecycle and operator-approved privileges |
The **Agent API** is the Neuron's main HTTP API. “Agent” means the application acts through the Agent endpoint rather than connecting directly over XMPP while holding the corresponding private keys. It is unrelated to AI agents.
## Platform objects
A typical trusted workflow crosses multiple layers:
```text theme={null}
Account → key → Legal Identity → contract role → signature
│
├→ Neuro-Feature → state → history
└→ wallet operation → transaction state
```
Read the [object model](/platform/object-model) before designing persistence or lifecycle handling.
## Federation and deployment
A Neuron belongs to an operator-controlled environment. Cross-domain behavior depends on the deployed services, privileges, trust relationships, and federation configuration. Applications must receive an exact Neuron host and an environment contract from the operator; they must not infer production reach from a successful local request.
## Choose what to read next
* [Choose an integration](/get-started/choose-integration)
* [Prepare a development environment](/get-started/environments)
* [Trust and federation](/platform/trust-and-federation)
# Keys and signatures
Source: https://docs.neuro-tech.io/platform/keys-and-signatures
Choose where keys are managed and store the identifiers needed for signatures
Keys connect authenticated actors to signed identities, agreements, and data. Applications should treat key creation, key identifiers, signing authority, and signature verification as separate concerns.
## Choose who manages keys
| Integration | Where keys are managed |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent API or an SDK built on it | The application asks the Neuron's Agent interface to perform supported cryptographic operations; it does not behave like a direct XMPP client holding those private keys |
| Direct XMPP client | The client owns the direct connection and private keys |
| MCP | The AI application receives only the scoped tools made available by the MCP server; it must not infer access to arbitrary signing operations |
The Agent API acts through the Neuron's Agent interface. Its name does not indicate an AI-agent-specific API.
## Key workflow
```text theme={null}
Choose a supported algorithm
↓
Create a key in the correct account context
↓
Persist the returned key identifier
↓
Associate it with the identity or signing workflow
↓
Verify the resulting signature or signed object
```
Do not hard-code an algorithm across a long-lived application unless the supported workflow requires it. Query or follow the algorithm guidance for the Neuron version you target.
## Application rules
* Keep passwords, JWTs, key passwords, private keys, and signing secrets out of source control and logs.
* Persist returned identifiers rather than parsing them from display text.
* Make the actor, key, payload, and intended signing purpose explicit.
* Do not claim legal effect or non-repudiation solely because bytes have a valid cryptographic signature; the identity, authorization, contract, policy, and verification context also matter.
* Treat retries carefully. A signing operation may have effects that should not be duplicated unless idempotency is explicitly documented.
## Build with signatures
* [Create cryptographic keys](/neuron-api/guides/creating-cryptographic-keys)
* [Digital signatures](/build/digital-signatures/overview)
* [Cryptography reference](/neuron-api/api-reference/cryptography/overview)
# Neuro-Features and state machines
Source: https://docs.neuro-tech.io/platform/neuro-features-and-state-machines
Learn how contracts create digital features with lifecycle state, ownership, and history
A **Neuro-Feature** is a contract-related digital feature that an application can retrieve together with its attributes and event history. A related **state machine** can make allowed lifecycle states and transitions explicit.
## Relationship model
```text theme={null}
Approved creation template
↓
Creation contract
↓
Neuro-Feature identifier
├── attributes and description
├── current owner or holder data exposed by the API
├── current state
└── notes and event history
```
The exact creation and transfer sequence must come from a verified template and supported Neuron build. The existence of read operations does not prove that a guessed combination of contract and token operations will mint or transfer a feature.
## State-machine reasoning
For each stateful workflow, document:
| Question | Application requirement |
| ------------------------------ | --------------------------------------------------------------------- |
| What is the current state? | Read it from the documented operation or event |
| Which transitions are allowed? | Follow the approved contract/state-machine definition |
| Who can trigger a transition? | Check identity, party, role, and privilege requirements |
| Is the transition synchronous? | Handle accepted, pending, final, and failed outcomes as documented |
| What evidence remains? | Retain the feature/contract identifier and retrieve its event history |
## Available documentation
The [token guide](/neuron-api/guides/tokens-flow) covers inspection. No generic tutorial currently covers creation, state transitions, or ownership transfer; obtain those procedures from the target Neuron's operator.
## Reference
* [Tokens](/neuron-api/api-reference/tokens/overview)
* [State machines](/neuron-api/api-reference/state-machines/overview)
# Neuro object model
Source: https://docs.neuro-tech.io/platform/object-model
See how accounts, identities, contracts, assets, states, wallets, and transactions relate
Neuro applications work with several long-lived objects. Use this map to decide which identifiers and state your application must store.
This diagram explains application concepts; it is not an API schema. Use the generated operation pages for exact request and response fields.
## Relationship map
```text theme={null}
Neuron
└── hosts Account access and application-facing services
Account
├── uses Keys
├── can apply for Legal Identities
└── accesses Wallet capabilities
Legal Identity
├── identifies a Contract Party
└── participates under a Contract Role
Smart Contract
├── defines Parties and Roles
├── contains Parameters and human-readable text
└── may define a State Machine and Neuro-Feature creation
Neuro-Feature
├── is associated with its creation contract
├── may have State Machine state
└── has an event and provenance history
Wallet
└── exposes balances and Transactions
```
## Objects your application may store
| Object | Created by | Identifier to persist | Mutable state | Related workflow |
| -------------- | --------------------------------------- | ---------------------------------------------------- | --------------------------------------------- | ----------------------- |
| Neuron | Operator | Host/domain | Configuration and installed capabilities | Environment setup |
| Account | Onboarding flow or operator | Account identifier or username as defined by the API | Verification, session, privileges | Verified identity |
| Key | Account through cryptographic operation | `keyId` when returned | Key lifecycle requires verification | Signatures and identity |
| Legal Identity | Account application plus review | `legalId` | Application and approval state | Verified identity |
| Smart Contract | Creator from an approved template | Contract ID | Proposal, signing, and lifecycle state | Agreement |
| Party and Role | Contract template and instance | Contract-defined identity/role references | Participation and signature state | Agreement |
| Neuro-Feature | Approved creation-contract workflow | Token/feature ID | Ownership, notes, events, state-machine state | Product passport |
| State Machine | Contract/template definition | Contract or feature association | Current state, variables, reports | Asset lifecycle |
| Wallet | Neuron account capability | Confirm with wallet API | Balance and pending transactions | Payments |
| Transaction | Wallet/payment workflow | Transaction ID | Provider-specific transaction state | Payments |
## Store returned identifiers and state
When an operation creates or retrieves a long-lived object, store the identifier returned by that operation. For asynchronous work, also store the latest returned status and the mechanism used to check for changes.
# Neuro platform
Source: https://docs.neuro-tech.io/platform/overview
Learn how Neurons, accounts, identities, contracts, assets, and trust services fit together
Applications connect to a Neuron to use accounts, identities, contracts, digital assets, payments, messaging, and storage. Start with the object model, then open only the concepts your application uses.
## Start with the object model
Read the [Neuro object model](/platform/object-model) to understand which objects an application creates, owns, references, and persists.
## Platform capabilities
| Capability | What it contributes | Build with it |
| -------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------- |
| [Accounts and Legal Identities](/platform/accounts-and-identities) | Actors and reviewed identity | [Verified identity](/build/verified-identity/overview) |
| [Keys and signatures](/platform/keys-and-signatures) | Cryptographic authorization and evidence | [Digital signatures](/build/digital-signatures/overview) |
| [Smart contracts](/platform/smart-contracts) | Human- and machine-readable agreements | [Agreements](/build/agreements/overview) |
| [Neuro-Features and state machines](/platform/neuro-features-and-state-machines) | Assets and auditable lifecycle | [Tokenized assets](/build/tokenized-assets/overview) |
| Neuro-Ledger | Distributed audit and history | [Neuro-Ledger](/neuro-ledger/overview) |
| [Wallets and payments](/platform/wallets-and-payments) | Value and transaction workflows | [Payments](/build/payments/overview) |
| Neuron | Federated runtime and extension host | [What is the Neuron?](/overview/what-is-the-neuron) |
## Where to go next
Use [Build](/build/overview) for application guides and [API reference](/neuron-api/api-reference/overview) for HTTP request details. Use Neuron development and operations documentation only when you extend or administer a Neuron.
Start with [Platform architecture](/platform/architecture), then use [Trust and federation](/platform/trust-and-federation) for cross-domain decisions.
# Smart contracts
Source: https://docs.neuro-tech.io/platform/smart-contracts
Learn how templates, parties, roles, parameters, and signatures form a contract
A Neuro smart contract is a structured agreement. Its machine-readable parts, human-readable text, participating parties, roles, parameters, signatures, and lifecycle rules must describe the same intended agreement.
## Template and instance
```text theme={null}
Template
├── allowed parameters
├── roles and parts
├── human-readable rendering
└── optional lifecycle or state-machine rules
↓ instantiate
Contract instance
├── concrete parameter values
├── identified parties in roles
├── proposal and signature state
└── current lifecycle state
```
Template approval and contract signing are different states. An approved template can be instantiated, but an instance is not a completed agreement until its own participation and signature requirements have been satisfied.
## Application responsibilities
* Use a template whose approval and compatibility are confirmed for the target Neuron.
* Bind Legal Identities to the intended parties and roles.
* Validate parameters before presenting human-readable text for signature.
* Persist the contract identifier and current proposal/signature state.
* Display the same material terms the application submits.
* Treat proposal, signature, and finalization as lifecycle states, not one synchronous request.
* Retrieve and verify the final contract rather than assuming the last command completed the workflow.
## Learn, build, reference
* **Overview:** [Agreements](/build/agreements/overview)
* **Quickstart:** [Contracts quickstart](/contracts/quickstart)
* **Guides:** [Agent API contract guide](/contracts/agent-api-quickstart)
* **Concepts:** [Templates and instances](/contracts/templates-and-instances), [roles and parts](/contracts/roles-and-parts), and [lifecycle](/contracts/lifecycle)
* **Reference:** [Contract operations](/neuron-api/api-reference/contracts/overview)
# Trust and federation
Source: https://docs.neuro-tech.io/platform/trust-and-federation
Decide which operators, providers, domains, and remote Neurons your application trusts
Neuro deployments are operator-controlled and can participate in federated workflows. Applications therefore need to ask both **who attests a fact** and **where that attestation is accepted**.
## Separate the trust decisions
| Decision | Example question |
| ---------------------- | ------------------------------------------------------------------------- |
| Authentication | Which account is controlling this session? |
| Identity review | Which provider reviewed the identity, under which policy? |
| Authorization | Is this account allowed to perform this operation? |
| Contract participation | Does this Legal Identity satisfy the party and role requirements? |
| Federation | Will the relevant Neurons and domains exchange and accept this operation? |
| Application acceptance | Does the relying application accept the returned status and evidence? |
A successful HTTP response only answers the operation-level question. It does not automatically answer every policy or cross-domain question above.
## Confirm which Neuron and domain you trust
The application connects to an exact Neuron host supplied by its operator. The Neuron's enabled packages, providers, privileges, templates, and federation relationships determine which workflows can complete.
Before relying on cross-domain behavior, confirm:
* the participating Neurons and identities;
* the Trust and Identity Providers involved;
* the accepted template or workflow policy;
* required privileges and authorization grants;
* event or polling behavior for remote state changes;
* development, staging, and production federation boundaries.
## Design for asynchronous results
Review, approval, proposal, signature, and remote operations can remain pending after the initiating request. Persist the returned identifier and state, then use the documented event, callback, XMPP, or polling mechanism for that deployment. Do not translate “request accepted” into “business workflow complete.”
## Apply the trust model
* [Development and production environments](/get-started/environments)
* [Security and transport](/neuron-api/security-and-transport)
* [Messaging](/neuron-api/guides/messaging)
* [Events and webhooks](/neuron-api/guides/webhooks)
# Wallets and payments
Source: https://docs.neuro-tech.io/platform/wallets-and-payments
Separate balances, payment initiation, provider flows, and transaction lifecycle state
Wallet and payment integrations combine account authorization, value semantics, provider selection, initiation, and asynchronous transaction state. A balance read and a completed payment are different workflows.
## Transaction model
```text theme={null}
Authorized account
↓
Confirm environment and value semantics
↓
Read balance and supported provider/options
↓
Initiate an operator-approved payment flow
↓
Persist transaction identifier
↓
Observe pending → finalized or failed
↓
Reconcile balance and audit information
```
## Protect credentials and value
* Confirm whether the environment contains test value or real value.
* Confirm the supported wallet/payment product and provider before initiating anything.
* Do not infer financial harmlessness from a hostname containing words such as `dev`, `test`, or `sandbox`.
* Require explicit human approval before an AI application performs a value-moving tool call unless a separately approved policy defines a safe autonomous boundary.
* Keep credentials and bearer tokens out of browser code and logs.
* Do not retry initiation blindly; use documented idempotency and transaction-state behavior.
## Product availability
Agent API wallet operations and Neuro-Pay are separate interfaces. Ask the Neuron operator which product and provider are supported before implementing a payment flow.
## Build a payment integration
* [Build a payment integration](/build/payments/overview)
* [Wallet reference](/neuron-api/api-reference/wallet/overview)
* [Prepare a development environment](/get-started/environments)
# Content, Markdown, and generated documents
Source: https://docs.neuro-tech.io/protocols/content-and-markdown
Use Neuron's media-type pipeline to decode, transform, render, and serve content
Neuron's `InternetContent` inventory discovers encoders, decoders, converters, and file-extension mappings from installed assemblies. The same typed object can therefore be rendered differently according to `Accept`.
## Common formats
The runtime can support JSON, XML, forms, binary streams, Markdown/HTML, CSV/TSV, images, PDF, ZIP, JWT/JWS, RDF/Turtle/JSON-LD, SPARQL results, Graphviz, PlantUML, and Office documents. The exact set depends on packages and external programs.
## Markdown pages
Markdown is an application format in Neuron, not only static documentation. Page metadata can select a master page, styles, scripts, JavaScript, author/date, navigation, and other renderer-specific features. Script expressions can make content dynamic.
Use packages to deploy pages so assets, master pages, scripts, and routes are versioned together.
## Conversion pipeline
```text theme={null}
Input bytes + Content-Type
-> decoder -> typed object
-> optional converter chain
-> encoder selected by Accept
-> response bytes + Content-Type
```
Return `415` when input cannot be decoded, `406` when no acceptable output exists, and `422` when the decoded object cannot be processed/serialized for the requested operation.
## Document generation
Markdown can be rendered to HTML and, with the corresponding modules, PDF and JavaScript. Graphviz and PlantUML blocks require their runtime dependencies. Treat document conversion as resource-intensive untrusted-input processing: bound size/time, disable unsafe external includes, and isolate temporary files.
## API design
* Send explicit `Content-Type` and `Accept`.
* Do not label arbitrary text as JSON/XML.
* Keep character sets explicit for text.
* Use typed error bodies.
* Avoid depending on an optional encoder without declaring the package dependency.
# HTTP proxy
Source: https://docs.neuro-tech.io/protocols/http-proxy
Use Neuron as an authenticated, policy-controlled HTTP egress service
The generic HTTP proxy is exposed at `/HttpProxy` in builds that include the service. It lets an authenticated client retrieve a target through the Neuron, useful when the client platform cannot access an HTTP-only resource or when egress must use the Neuron's network and client certificate.
## Authentication
The resource can accept:
* normal HTTP authentication;
* a logged-in web session;
* JWT bearer token;
* mutual TLS when enabled.
An XMPP client can obtain a Neuron JWT through the HTTP-over-XMPP extension and use it for protected HTTP resources.
## Use safely
An unrestricted proxy can become an SSRF and abuse service. Configure:
* allowed schemes, hosts, ports, and methods;
* blocks for loopback, link-local, private, and cloud-metadata addresses;
* redirect validation at every hop;
* request/response size and time limits;
* removal of caller credentials on cross-origin redirect;
* role and WAF restrictions;
* audit events containing actor, destination, method, and result.
## Choose between proxy options
| Option | Use |
| -------------------------------- | --------------------------------------------------------- |
| `/HttpProxy` | Application-controlled HTTP access |
| `/MCP/Content` | AI agent tool calls with MCP schemas and privileges |
| Reverse proxy resource | Publish a fixed upstream application under a Neuron route |
| Direct `InternetContent` library | Trusted in-process package code |
If a client can securely reach the target directly, a proxy adds operational and security cost without benefit.
# OAuth 2 authorization server
Source: https://docs.neuro-tech.io/protocols/oauth
Register clients, authorize scopes, issue JWTs, use device flow, and introspect tokens
OAuth settings differ by Neuron version and operator configuration. Read the server metadata and confirm grants, registration, scopes, and token behavior before production use.
Current Neuron builds can act as an OAuth 2 authorization server.
## Endpoints
| Purpose | Path | Standard |
| --------------------------- | ----------------------------------------- | ------------- |
| Authorization | `/oauth/authorize` | RFC 6749 |
| Token | `/oauth/token` | RFC 6749 |
| Dynamic registration | `/oauth/register` | RFC 7591/7592 |
| Registration management | `/oauth/registration` | RFC 7592 |
| Device authorization | `/oauth/device` | RFC 8628 |
| Introspection | `/oauth/introspect` | RFC 7662 |
| Authorization metadata | `/.well-known/oauth-authorization-server` | RFC 8414 |
| Protected-resource metadata | `/.well-known/oauth-protected-resource` | RFC 9728 |
PKCE and refresh tokens are supported. Use server metadata to discover the grants, signing algorithms, and client-authentication methods enabled by the running build.
## Choose a flow
* **Authorization Code + PKCE:** browser/mobile/desktop clients acting for a user.
* **Device authorization:** terminal, appliance, or agent without a usable browser.
* **Confidential client:** server-side application able to protect a secret.
* **mTLS or Neuron authentication exchange:** deployment-specific trusted client flows.
Do not use the implicit grant for new applications.
## Scopes to privileges
Neuron authorization is role-based. OAuth scopes map to privileges prefixed with `OAUTH.Scope.`, with colons changed to periods. An authenticated client receives a token only for scopes its backing account can authorize.
## Dynamic registration
The operator enables dynamic registration by creating an API key named `OAUTH`. Registrations are limited per remote endpoint. A registration creates a corresponding XMPP account with no useful privileges and normal XMPP communication disabled by default.
## Branding login pages
OAuth login UI is produced from Markdown and embedded into `MasterOAuth.md` in the web root. Package and version customizations; preserve CSRF, redirect-URI, consent, and error placeholders when changing the layout.
## Security checklist
* exact-match redirect URIs;
* PKCE for public clients;
* short-lived access tokens and protected refresh tokens;
* least-privilege scope grants;
* WAF restrictions for `/oauth/` where appropriate;
* never log codes, tokens, secrets, or verifier values;
* revoke/disable abandoned clients.
# Protocols and platform services
Source: https://docs.neuro-tech.io/protocols/overview
Choose the Neuron interface that matches your integration
Neuron is a multi-protocol server. The Agent API is one integration surface, not the whole platform.
| Need | Interface | Default resource/transport |
| ------------------------------------------------------------------ | -------------------------------- | ------------------------------------ |
| Server-side account, identity, contract, wallet, or token workflow | Agent API | `/Agent/...` over HTTPS |
| Give an AI agent tools and resources | MCP | `/MCP...` over HTTPS + OAuth |
| Real-time federated messaging and IoT | XMPP | C2S/S2S, WebSocket, or BOSH bindings |
| Standards-based authorization | OAuth 2 | `/oauth/...` |
| Decouple producers and consumers | Queue API | `/Queues/{queue}` |
| Query semantic data | SPARQL | `/sparql` |
| Read/write RDF graphs | Graph Store Protocol | `/rdf-graph-store` |
| Generate and serve rich content | Markdown/Script/content pipeline | Hosted resources and packages |
| Controlled outbound HTTP access | HTTP Proxy or Content MCP | `/HttpProxy` or `/MCP/Content` |
| Publish an open XMPP node to web readers | Public PubSub | `/PubSub/{nodeId}` RSS/XML |
| Exchange scannable platform actions | QR and URI services | `/QR/...` plus typed URI schemes |
## Choose a protocol
* Use XMPP when the interaction is real-time, federated, presence-aware, or device-oriented.
* Use Agent API when a trusted back end wants Neuron domain operations without maintaining XMPP state.
* Use MCP when an AI client needs discoverable, individually authorized tools.
* Use queues when a producer should not wait for a consumer.
* Use SPARQL/RDF when data semantics and graph relationships are the interface.
* Use packages and native modules for code that must run inside the Neuron.
All public interfaces require an explicit authentication, authorization, data-protection, retry, and audit design.
# Public publish/subscribe feeds
Source: https://docs.neuro-tech.io/protocols/public-pubsub
Expose an open XMPP PubSub node as RSS and retrieve its XML items over HTTP
Neuron maps XMPP Publish/Subscribe nodes with the `open` access model to a read-only public HTTP surface.
| Resource | Result |
| ------------------------------- | ---------------------------------------------- |
| `GET /PubSub/{nodeId}` | RSS 2.0 feed containing up to 20 recent items. |
| `GET /PubSub/{nodeId}/{itemId}` | Raw XML payload of one item. |
Both identifiers are URL-decoded by the server, so encode each path component rather than the complete path.
```js theme={null}
const nodeId = encodeURIComponent("ReleaseNotes");
const feed = await fetch(`https://neuron.example/PubSub/${nodeId}`, {
headers: { Accept: "application/rss+xml, application/xml;q=0.9" }
});
if (!feed.ok) throw new Error(`Feed failed: ${feed.status}`);
const rss = await feed.text();
```
## Access behavior
* A missing subpath returns `400 Bad Request`.
* An unknown node or item returns `404 Not Found`.
* A node that is not `open` returns `403 Forbidden`.
* Item bodies are returned as XML; the service does not convert arbitrary payloads to JSON.
* The feed orders items by most recent creation time and includes item links, publisher, dates, and stable object GUIDs.
Opening a node is a publication decision, not merely an XMPP configuration detail. Review existing items before changing the access model; previously published payloads can contain identifiers or content unsuitable for the public web.
## Web nodes
A PubSub node can also drive rendered web content. The `/PubSub/` route exposes the source feed/item XML, while a separately configured web-node route can render the information as a site. Keep source payload compatibility and presentation versioning separate.
## Consumer rules
* Treat item XML as untrusted input and disable unsafe external entity processing.
* Use item IDs or feed GUIDs for deduplication.
* Poll with cache validators/backoff; do not assume an event stream.
* Follow item links only on the expected Neuron origin.
* Use authenticated XMPP PubSub for non-public data or publishing operations.
# QR codes and Neuro URI schemes
Source: https://docs.neuro-tech.io/protocols/qr-and-uri-schemes
Generate QR images and safely route identity, contract, signature, discovery, onboarding, payment, and token links
Client support and security rules differ by URI scheme. Confirm the scheme, namespace, cryptography, expiry, and one-time-use behavior before generating production links.
A Neuro QR code carries a URI. The QR image has no authority by itself: parse the URI, resolve the responsible domain, show the intended action, and require consent before a signature, transfer, login, claim, or control operation.
## Generate a QR image
```http theme={null}
GET /QR/{url-encoded-text}?w=400&h=400&q=2&fg=Theme&bg=Theme
```
| Parameter | Default | Meaning |
| ----------- | ---------------- | ------------------------------------------------------------------------- |
| `w`, `h` | `400` | Output width and height in pixels. |
| `fg`, `bg` | `Black`, `White` | Dot/background colors; `Theme` selects current theme colors. |
| `c` | Scheme-specific | Center icon color. |
| `mc`, `omc` | Derived | Marker and outer-marker colors. |
| `ac`, `oac` | Derived | Alignment and outer-alignment colors. |
| `q` | `1` | Samples calculated per output pixel for antialiasing. Increase for print. |
Encode the entire text as one path component. Explicitly set high-contrast colors and test with multiple scanners when producing print assets.
## Schemes
| Scheme | Carries |
| ----------- | ------------------------------------------------------------------------------------- |
| `iotid:` | Legal identity reference (`GUID@trust-provider-domain`). |
| `iotsc:` | Smart contract or template reference, optionally with proposed role/parameter values. |
| `iotdisco:` | Thing-registry discovery and ownership-claim metadata. |
| `tagsign:` | Short-lived request to initiate a signature/Quick Login petition. |
| `obinfo:` | Encrypted onboarding, recovery, or account-transfer locator. |
| `edaler:` | eDaler payment/value-transfer instruction. |
| `nfeat:` | Neuro-Feature token reference or operation. |
| `aes256:` | Package-defined encrypted content reference. |
Use the corresponding platform parser/client library. Unknown query parameters must not silently become signed contract values or payment fields.
## Smart contract links
The minimum contract form is:
```text theme={null}
iotsc:CONTRACT_ID@DOMAIN
```
For a template, URI query parameters can propose `Visibility`, a recipient `Role`, known role-to-Legal-ID assignments, and initial parameter values:
```text theme={null}
iotsc:2a746d98-27a9-951f-8816-5dce5960eb0d@legal.example?Visibility=CreatorAndParts&Role=Buyer&Currency=EUR&Value=340
```
Treat every value as an untrusted proposal. Fetch and validate the template, canonicalize typed parameters, render the final human-readable contract, and ask the signer to review it.
## Signature links
`tagsign:{requestor-jid},{base64url-key}` asks a client to start a signature petition. The client sends `` to the named party; the resulting petition uses the current legal-identity namespace `urn:nf:iot:leg:id:1.0` (legacy peers may advertise the IEEE namespace).
The key is short-lived. Bind approval UI to requestor, purpose, content hash, target endpoint, Legal ID, and expiry. Declining must not create a signature.
## Onboarding links
```text theme={null}
obinfo:DOMAIN:CODE:BASE64_KEY:BASE64_IV
```
The consumer POSTs the code as `text/plain` to `https://DOMAIN/Onboarding/GetInfo` with `Accept: text/plain`, Base64-decodes the response, then decrypts and validates the onboarding XML with the supplied key and IV. Current flows use AES-CBC and PKCS#7 padding; use the platform onboarding implementation because key length and one-time policy depend on the producer.
Partial onboarding can be reusable; full/recovery and transfer payloads are normally one-time and short-lived. An `obinfo` URI is equivalent to a credential—never log, preview, analytics-track, or sync it through an untrusted service.
## Multi-purpose QR package
When the optional MultiQR package is installed, `/MultiQR.md` creates a landing page containing one or more labeled links or embedded media. Definitions can have an expiry, use limit, custom master, color scheme, and counter category. Script packages can call `CreateMultiQR(definition, "/MultiQR.md")` and receive `{ Image, Page }` URLs.
Validate every embedded URL/media type and avoid placing secrets in a multi-purpose page: the page link can be copied even when the original QR was shown privately.
# Queue API
Source: https://docs.neuro-tech.io/protocols/queues
Enqueue, peek, dequeue, batch, wait, and clear typed items over HTTP
The Queue API at `/Queues/{queueName}` provides authenticated FIFO queues with content decoding/encoding and delayed responses.
## Methods
| Method | Operation | Success |
| ----------------------- | ------------------------------------- | ------------------------------------ |
| `GET /Queues` | API documentation | `200` |
| `PUT /Queues/{name}` | Enqueue request body | `204` |
| `POST /Queues/{name}` | Dequeue, or peek with query parameter | `200` with item, `204/404` when none |
| `DELETE /Queues/{name}` | Clear all items | `204` |
## Authorization
The account needs:
```text theme={null}
Admin.Queues..
```
For example:
```text theme={null}
Admin.Queues.InvoiceEvents.Enqueue
Admin.Queues.InvoiceEvents.Dequeue
```
Supported authentication includes mTLS, JWT bearer, and configured HTTP authentication schemes. HTTPS with at least 128-bit security is required when encryption is enabled.
## Enqueue
```bash theme={null}
curl --fail -X PUT \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data '{"invoiceId":"inv-123"}' \
"https://neuron.example.com/Queues/InvoiceEvents?Timeout=30000"
```
The server first decodes the request by `Content-Type`, then serializes the resulting object for the queue. Expect `415` for an unsupported type and `422` when the decoded object cannot be serialized.
## Dequeue or peek
```bash theme={null}
curl --fail -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
"https://neuron.example.com/Queues/InvoiceEvents?Timeout=30000"
```
Use `Peek=1` to read without removal. Use `Count=N` for a batch; batches are returned as `multipart/mixed`, even when `N=1`. `MinTimeout` waits briefly for the remainder after the first item arrives.
| Query | Applies to | Range/default |
| ------------ | ------------ | --------------------------------- |
| `Timeout` | PUT, POST | 0–90000 ms; default 30000 |
| `Count` | POST dequeue | 1+; default 1 |
| `MinTimeout` | Batched POST | 0–`Timeout` |
| `Peek` | Single POST | 0 or 1; incompatible with `Count` |
Use HTTP/2 so many delayed dequeue requests can share a connection efficiently.
## Consumer design
Dequeue removes the item, so persist the business result before considering processing complete. Use an application idempotency key because a caller can fail after the server dequeues but before the caller records success.
# Security utility APIs
Source: https://docs.neuro-tech.io/protocols/security-utilities
Use mTLS diagnostics, endpoint reputation, QR resources, and protected storage
Neuron packages expose several focused security services.
## mTLS ping
The mTLS test package provides a page, API, client library, unit tests, and CLI that report connection information and any client certificate received by the Neuron. Use it to separate network/TLS termination problems from application authorization.
Verify:
* the client sent a certificate;
* no reverse proxy stripped it;
* subject/issuer and chain are expected;
* key usage and validity interval permit client authentication;
* the application maps the certificate to the intended account.
Do not return full certificate or connection diagnostics to unauthenticated Internet callers in production.
## What's My Endpoint
`GET` or `POST /WMEP` returns the request's observed remote endpoint as `text/plain`. It helps diagnose NAT and proxy paths. Treat forwarded headers as trusted only when they came from a configured proxy.
## DNS over HTTPS
`/dns-query` implements the RFC 8484 wire format:
* `GET /dns-query?dns={base64url-dns-message}` with `Accept: application/dns-message`;
* HTTPS `POST /dns-query` with `Content-Type: application/dns-message`.
The response preserves the query ID, returns `application/dns-message`, and can include `Cache-Control` for GET. Unencrypted POST is rejected. A Neuron DoH endpoint is a resolver service: apply abuse controls, query logging/privacy policy, recursion policy, and outbound DNS hardening before exposing it publicly.
## Open intelligence
The Agent API can check login-auditor state and create/query/update/delete expiring intelligence records about endpoints. See [Open intelligence reference](/neuron-api/api-reference/open-intelligence/overview).
## QR APIs
QR resources generate single or multi-purpose codes for text and platform URI schemes such as onboarding, discovery, signatures, payments, or remote login. A QR code is only an encoding; validate the decoded URI scheme, origin, expiry, signature, and intended action before displaying a confirmation or executing it.
See [QR codes and Neuro URI schemes](/protocols/qr-and-uri-schemes) for endpoint parameters and secure dispatch behavior.
## Vault and private storage
Use the Agent vault endpoints for protected application content and the PCI-oriented vault package where its compliance boundary applies. A vault reference is not public authorization: authenticate, check object ownership/access, and avoid leaking retrieval links into logs.
# SPARQL and RDF Graph Store
Source: https://docs.neuro-tech.io/protocols/semantic-web
Query and manage semantic graphs with standard HTTP protocols
The semantic-web module registers:
```text theme={null}
/sparql
/rdf-graph-store
```
Both resources require an authenticated user with the operation-specific privilege configured by the module.
## SPARQL endpoint
`/sparql` accepts GET and POST queries. The Script parser supports SPARQL `SELECT`, `ASK`, and `CONSTRUCT`. Use POST for long queries and send the correct SPARQL media type.
```bash theme={null}
curl --fail -X POST https://neuron.example.com/sparql \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/sparql-query" \
-H "Accept: application/sparql-results+json" \
--data 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 100'
```
Result negotiation supports standard SPARQL result encodings and, when installed, HTML, CSV, and tab-separated renderers.
## Graph Store Protocol
`/rdf-graph-store` implements GET, POST, PUT, and DELETE over the default or a named graph.
* `GET` retrieves a graph.
* `POST` merges triples into a graph.
* `PUT` replaces a graph.
* `DELETE` removes a graph.
Identify named graphs with the standard graph query parameter expected by the endpoint. Use RDF media types such as Turtle, RDF/XML, or JSON-LD that the running Neuron advertises.
## Operational guidance
* Put `LIMIT` on exploratory queries.
* Restrict mutation privileges separately from query.
* Validate and bound remote graph dereferencing.
* Invalidate application caches after graph updates.
* Treat blank-node identifiers as document-local.
* Version domain vocabularies and contract/harmonized-interface namespaces.
# XMPP federation and email bridging
Source: https://docs.neuro-tech.io/protocols/xmpp-and-email
Use JIDs, presence, rosters, federation, and the optional SMTP bridge
XMPP is Neuron's real-time federation layer. A bare JID has the form `account@domain`; a connected resource uses `account@domain/resource`.
## Federation
A client authenticates to its home Neuron. For a remote-domain JID, the home broker establishes an authenticated server-to-server connection to the remote broker and routes the stanza. Federation gives global reach without a central message hub.
## Presence and consent
Roster relationships and presence subscriptions are part of authorization and anti-abuse design:
1. request a subscription;
2. the contact accepts or declines;
3. each side receives the presence allowed by the relationship;
4. unsubscribe and remove roster items when the relationship ends.
Do not send automated messages to arbitrary JIDs merely because federation can route them.
## Stanza types
| Stanza | Use |
| ---------- | ------------------------------------------------------ |
| `message` | Chat, notifications, and application payloads |
| `presence` | Availability and subscription state |
| `iq` | Request/response or set operations with structured XML |
Use end-to-end encryption for sensitive content that must remain private across brokers.
## Email bridge
When SMTP is enabled, an XMPP account can send and receive email through the same address. Incoming email becomes XMPP message content; outgoing XMPP text/Markdown/HTML is converted to an email after a short accumulation window.
Unlike ordinary email, the bridge enforces a presence/allowlist relationship. A first-time email sender receives a link to request presence; delivery proceeds after the XMPP recipient accepts.
Advanced email content and attachments require a client that understands the Neuron email XMPP extension. Plain text remains interoperable with basic clients.
## SMTP troubleshooting
* verify MX and SPF DNS records;
* inspect per-sender/recipient SMTP logs under the Neuron program-data SMTP folder;
* distinguish `IN` and `OUT` logs;
* resolve the expected incoming sender hosts from SPF and outgoing recipient hosts from MX;
* check roster subscription before investigating content conversion.
# Data and persistence
Source: https://docs.neuro-tech.io/script/data-and-persistence
Query and mutate Neuron objects, external databases, semantic data, and ledger records
The `Waher.Script.Persistence` extension adds SQL-like statements over Neuron's object database. The syntax looks familiar, but sources are .NET types, object collections, vectors, or XML—not relational tables by default.
## Inspect a type
```text theme={null}
Properties(RuntimeCounter)
```
If two loaded assemblies define the same local type name, use the fully qualified .NET type name.
## Select objects
```text theme={null}
SELECT TOP 100
ObjectId,
Key,
GetCounter(Key) AS CurrentValue
FROM RuntimeCounter
WHERE Key LIKE "XMPP.%"
ORDER BY Key
```
Features include projection, aliases, filtering, ordering, grouping, aggregates, implicit groups, wildcards, pagination, and selecting a single object.
Collection names can collide with namespaces. Quote the label to force collection interpretation:
```text theme={null}
SELECT count(*) FROM "RuntimeCounters"
```
## Insert
The engine supports:
```text theme={null}
INSERT INTO CollectionName (Field1,Field2)
VALUES (Value1,Value2)
```
It also supports `INSERT SELECT`, `INSERT OBJECT`, and `INSERT OBJECTS` forms. Prefer inserting typed objects through a package API when invariants or events must be maintained.
## Update and delete
```text theme={null}
UPDATE ExampleType
SET Enabled=false
WHERE ObjectId=TargetId
```
```text theme={null}
DELETE FROM ExampleType
WHERE ObjectId=TargetId
```
Direct mutation can bypass domain workflows, signatures, notifications, and audit events. Use it for owned operational data, migrations, and recovery procedures—not to alter legal identities, signed contracts, ledger history, or token history.
## Indexes and collections
`CREATE` and `DROP` statements can manage indexes and collections. Run schema operations from a versioned migration with a backup and an idempotent existence check.
## External SQL databases
The `Waher.Script.Data` family can open external connections, execute provider SQL, call stored procedures, and close connections. MySQL and PostgreSQL extensions add provider-specific support. Always parameterize external input and close connections in `finally`.
## Semantic data
With semantic and persistence extensions loaded, Script can execute SPARQL `SELECT`, `ASK`, and `CONSTRUCT` queries. Use the Neuron's SPARQL and graph-store HTTP APIs for cross-process integrations; use Script for local transforms and reports.
## Ledger records
Ledger extensions add `RECORD OBJECT`, `RECORD OBJECTS`, and `REPLAY`. Ledger recording is append-oriented and auditable; it is not a replacement for mutable operational persistence. Record domain events whose history must be provable, then build current projections separately.
# Extend the Script engine
Source: https://docs.neuro-tech.io/script/extend-the-engine
Publish a typed C# function from a Neuron package
Create a Script function when multiple pages, reports, or jobs need the same tested domain operation. The runtime discovers public function classes from loaded assemblies.
## Minimal scalar function
```csharp theme={null}
using Waher.Script;
using Waher.Script.Abstraction.Elements;
using Waher.Script.Functions;
using Waher.Script.Model;
using Waher.Script.Objects;
public sealed class CelsiusToKelvin : FunctionOneScalarVariable
{
public CelsiusToKelvin(ScriptNode argument, int start, int length,
Expression expression)
: base(argument, start, length, expression)
{
}
public override string FunctionName => nameof(CelsiusToKelvin);
public override IElement EvaluateScalar(IElement argument,
Variables variables)
{
double celsius = Expression.ToDouble(argument.AssociatedObjectValue);
return new DoubleNumber(celsius + 273.15);
}
}
```
Select the appropriate base class for zero, one, two, or multiple arguments and for scalar versus vector-aware evaluation. Use an asynchronous base/interface when the operation performs I/O.
## Design rules
* Validate types and ranges at the boundary.
* Keep `FunctionName` stable; changing it breaks scripts.
* Declare aliases only for intentional compatibility.
* Provide `DefaultArgumentNames` so generated help is meaningful.
* Return Script `IElement` values or supported .NET objects consistently.
* Honour cancellation and timeouts for I/O.
* Avoid hidden global state.
* Log externally visible side effects.
* Never expose secrets through exceptions or object properties.
## Inventory discovery
The runtime inventory finds the class when its assembly package loads. If the function does not appear:
1. confirm the assembly is in the package manifest;
2. check that its target framework matches the Neuron;
3. inspect module/inventory startup events;
4. verify the class is public and concrete;
5. ensure all referenced assemblies are installed.
## Test from C# and Script
Unit-test scalar conversion and invalid input directly. Then install the package in a test Neuron and evaluate:
```text theme={null}
CelsiusToKelvin(0)
```
Expected result:
```text theme={null}
273.15
```
Document the function in the package's Mintlify section and include at least one copyable example and failure case.
# Script language basics
Source: https://docs.neuro-tech.io/script/language-basics
Syntax for values, collections, assignment, functions, conditions, loops, and errors
Neuron Script is expression-oriented: statements evaluate to values, and collections participate in vectorized mathematical operations.
## Primitive values
```text theme={null}
42
3.14159
1.2e-3
true
false
"text"
'also text'
null
```
The engine also supports big integers, rational and complex numbers, dates and times, physical quantities with units, XML, and .NET objects supplied by the host.
## Assignment
Use `:=` to assign:
```text theme={null}
Name:="Ada";
Retries:=3;
Enabled:=true;
```
Assignment returns the assigned value. Keep side effects on their own lines in shared scripts.
## Collections
```text theme={null}
Vector:=[1,2,3,4];
Matrix:=[[1,2],[3,4]];
EmptyObject:={};
EmptyObject["key"]:="value";
```
Ranges and comprehensions make data pipelines concise:
```text theme={null}
Squares:=[x^2:x in 1..10];
EvenSquares:=[x in Squares:x mod 2=0];
```
## Functions and lambdas
```text theme={null}
Square(x):=x^2;
Square(9)
```
Canonical extensions let functions apply across vectors and other algebraic structures when their implementation supports it. Test the shape of returned values instead of assuming every scalar function vectorizes.
## Conditions
All of these return values:
```text theme={null}
if Temperature>30 then "hot" else "normal"
Temperature>30 ? "hot" : "normal"
PossiblyNull ?? "fallback"
```
Keywords such as `IF`, `THEN`, and `ELSE` are case-insensitive.
## Iteration
```text theme={null}
Sum:=0;
for i:=1 to 10 do
Sum:=Sum+i;
Sum
```
```text theme={null}
Names:=[];
foreach User in Users do
PushLast(User.UserName,Names);
Names
```
The language also supports `while`, `do/while`, `break`, `continue`, `return`, and `try/catch/finally` forms.
## Pattern matching
Assignment can destructure values and XML patterns. Treat a failed match as a normal branch in parsers, and validate input before using values in a database statement or .NET call.
## Comments and formatting
Use comments to explain policy and non-obvious constraints, not direct translations of the next expression. Terminate statements with semicolons when a newline could be ambiguous.
## Namespaces and .NET
Script can reference discovered .NET namespaces and types, call static methods, create objects, access properties, and use operators supplied by objects. This is powerful but tightly couples a script to loaded assemblies. Package reusable functionality as a named Script function when you need a stable interface.
# Neuron Script
Source: https://docs.neuro-tech.io/script/overview
Automate a Neuron with its compact, extensible, mathematical scripting language
Neuron Script is the language implemented by `Waher.Script`. It is not JavaScript or ECMAScript. It is a compact expression language designed for mathematics, data queries, dynamic content, reports, automation, and direct integration with .NET objects.
## What you can build
* operational queries and reports;
* dynamic Markdown, XML, HTML, images, and PDF content;
* scheduled jobs and event processing;
* database and ledger workflows;
* XMPP, email, contract, token, and payment automation;
* graphs, statistics, cryptography, semantic-web queries, and transforms;
* custom functions supplied by Neuron packages.
## Execution contexts
| Context | Typical use | Important inputs |
| ------------------ | ------------------------------------------- | ----------------------------------------------------------- |
| Script prompt | Interactive exploration and administration | Current user/session and prompt variables |
| Markdown page | Dynamic content embedded in a rendered page | HTTP request, response, session and page variables |
| Report | Parameterized, reusable operational output | Report parameters and server data |
| Job | Background or scheduled automation | Job configuration and runtime services |
| C# host | Evaluate expressions inside a module | Explicit `Variables`, cancellation and application services |
| Contract parameter | Validate a contract value | Other parameter values and contract client |
The function set is assembled from loaded modules. A bare `Waher.Script` host has core mathematical and runtime functions; a Neuron adds persistence, networking, content, gateway, contract, token, mail, and package-defined extensions.
## Learn in this order
Use the Script prompt and verify values and tables.
Values, assignment, collections, functions, and control flow.
Work with the object database, external SQL, SPARQL, and the ledger.
Turn scripts into reports, jobs, and repeatable procedures.
Script can call .NET APIs and mutate databases, files, accounts, contracts, and external services. Access to a Script prompt is administrative code-execution access unless the host deliberately restricts the available variables and types.
# Run your first script
Source: https://docs.neuro-tech.io/script/quickstart
Use the Neuron Script prompt to calculate, query, and format a result
After this guide, you can evaluate expressions, retain variables during a prompt session, and query the Neuron object database.
## Prerequisites
* A configured Neuron.
* A user role allowed to open the Script prompt.
* Read access to the data you intend to query.
## Open the prompt
From the administration UI, open **Script**. The prompt evaluates one expression or statement sequence and renders the resulting object using an available content renderer.
## Evaluate values
```text theme={null}
2+3*4
```
Expected result:
```text theme={null}
14
```
Assign with `:=` and separate statements with semicolons:
```text theme={null}
Radius:=5;
Area:=pi*Radius^2;
Area
```
## Work with vectors
```text theme={null}
Temperatures:=[18.2,19.1,21.0,20.4];
[
Min:=min(Temperatures),
Max:=max(Temperatures),
Average:=avg(Temperatures)
]
```
Function names are case-insensitive in normal Script usage, but keep the documented casing in shared code.
## Create objects
```text theme={null}
Status:={};
Status["Service"]:="Neuron";
Status["CheckedAt"]:=Now;
Status["Healthy"]:=true;
Status
```
## Query persisted objects
```text theme={null}
SELECT TOP 10
Key,
GetCounter(Key) AS CurrentValue
FROM RuntimeCounter
ORDER BY Key
```
Collections and types vary by installation. Start with a known application type or use `Properties(TypeName)` to inspect the fields available on persisted objects.
## Produce a table
Many query results render automatically. To transpose a vector of records into table form, use `T`:
```text theme={null}
Rows:=[
{Name:"alpha",Value:1},
{Name:"beta",Value:2}
];
Rows T
```
## Handle an error
```text theme={null}
try
Int("not-an-integer")
catch
"Calculation failed: "+Exception.Message
```
Do not expose raw exception messages to untrusted web users; log a correlation ID and return a safe message.
## Next steps
* [Language basics](/script/language-basics)
* [Data and persistence](/script/data-and-persistence)
* [Reports and automation](/script/reports-and-automation)
# Reports and automation
Source: https://docs.neuro-tech.io/script/reports-and-automation
Turn Script into parameterized reports, scheduled jobs, and operational workflows
File-based reports package a Script query with typed parameters and presentation. They let operators run a supported procedure without access to an unrestricted Script prompt.
## Build a report
1. Define one operational question, such as “Which XMPP counters changed between two labels?”
2. Declare the minimum parameters and safe defaults.
3. Validate parameter length, range, wildcard use, and permitted prefixes.
4. Query or calculate in Script.
5. Return a typed table, graph, or document.
6. Add empty-state and error output.
7. Package the report under the administrative **Sources & Nodes** tree.
## Counter comparison example
```text theme={null}
Sample:={};
foreach Counter in (SELECT Key FROM RuntimeCounter) do
Sample[Counter]:=GetCounter(Counter);
Sample
```
Persist labelled snapshots as an owned report object. Later, subtract dictionaries and filter zero differences:
```text theme={null}
Diff:=[foreach P in NewSample-OldSample:P];
[P in Diff:P.Value!=0]T
```
## Scheduled jobs
The jobs subsystem can run Script on a schedule or in response to application events. A production job should be:
* idempotent or protected by a durable operation key;
* bounded by time and batch size;
* explicit about time zone (prefer UTC internally);
* resumable after restart;
* observable through stable event IDs and counters;
* safe when two runtime nodes attempt the same work.
## Event queues
Use an encrypted FIFO queue when event producers and Script consumers run at different speeds. Dequeue in batches, commit the business result before acknowledging, and isolate poison messages.
## External effects
Neuron extensions let Script send XMPP messages and email, create or propose contracts, query tokens, and call payment services. Separate a workflow into:
```text theme={null}
Read -> Validate -> Decide -> Persist intent -> Perform effect -> Record outcome
```
This makes retries understandable. Do not send a payment or signature request directly from a report that users expect to be read-only.
## Parameter security
Do not interpolate report parameters into raw SQL, XML, paths, URLs, or .NET type names. Use typed parameters, allowlists, and the provider's parameter binding.
# Runtime functions and extensions
Source: https://docs.neuro-tech.io/script/runtime-functions
Find the function family that provides a Script capability
Script discovers functions from loaded assemblies. The exact catalog depends on the Neuron build and installed packages, but functions are organized into stable capability families.
## Core families
| Family | Examples of capability |
| -------------------- | -------------------------------------------------- |
| Analytic | powers, logarithms, trigonometry, calculus helpers |
| Scalar and complex | conversions, rounding, complex components |
| Strings | split, replace, trim, parse, evaluate |
| Date and time | components, UTC conversion, durations |
| Vectors and matrices | aggregates, transpose, inverse, determinant |
| Runtime | type creation, reflection, variables, flow helpers |
| Logging | structured event creation |
## Module families
| Assembly family | Capability |
| --------------------------- | -------------------------------------------------------------- |
| `Waher.Script.Persistence` | object SQL, indexes, persistence functions, SPARQL integration |
| `Waher.Script.Data.*` | external SQL, MySQL, PostgreSQL |
| `Waher.Script.Content` | encode, decode, and negotiate Internet content |
| `Waher.Script.Cryptography` | hashes, keys, signatures, encryption helpers |
| `Waher.Script.Xml*` | XML, XPath-like selection, XML signatures |
| `Waher.Script.Networking` | DNS and network operations |
| `Waher.Script.Graphs*` | charts, plots, 3D graphs |
| `Waher.Script.Statistics` | distributions and statistical functions |
| `Waher.Script.System` | operating-system integration |
| `Waher.Script.Threading` | parallel and synchronization helpers |
| `Waher.Content.*` | Markdown, semantic, XSL, images and document rendering |
| `Waher.Things.*` | sensor, actuator and concentrator objects |
## Neuron-specific functions
The IoT Broker package adds functions for:
* XMPP messaging, presence, roster lookup, ping, and IQ requests;
* contract creation, proposal, rejection, and obsoletion;
* token state, history, profiling, attachments, and actions;
* email messages, embedded resources, and attachments;
* country/locale and configured local services;
* runtime counters and administrative reporting.
Additional payment, KYC, Microsoft interoperability, SMS, OpenAI, and provider functions appear only when their packages are installed.
## Discover at runtime
Use reflection helpers such as `Functions`, `Methods`, `Properties`, `Fields`, and `Names` where available in the current context. For shared production code, declare the package dependency instead of dynamically guessing whether a function exists.
Function availability is an API surface. Package authors should document names, arguments, return shapes, side effects, privileges, and version changes.
# Web and content scripting
Source: https://docs.neuro-tech.io/script/web-and-content
Generate dynamic Markdown, XML, HTML, graphs, images, and responses
Neuron's content pipeline lets Script return rich objects instead of manually concatenating HTML. Installed encoders render tables, graphs, images, XML, Markdown, semantic data, and other types according to the requested content type.
## Dynamic Markdown
Use a Script block or the page's supported inline-expression syntax to calculate values during rendering. Keep queries above the presentation and return a small view model to the Markdown layer.
Conceptually:
```text theme={null}
Rows:=SELECT TOP 20 Key,GetCounter(Key) Value
FROM RuntimeCounter
ORDER BY Key;
Rows
```
The returned matrix/table is rendered by the active Markdown/content renderer.
## Generate XML
Script has a native XML syntax with embedded expressions and XML pattern matching. Prefer it over string concatenation because names, attributes, and values are encoded structurally.
Use XML for:
* contract machine-readable sections;
* XMPP information queries;
* gateway/module configuration;
* interoperable IoT payloads and schemas;
* transformations through XSL.
Validate generated XML against its XSD before signing or publishing it.
## Content negotiation
The runtime's `InternetContent` system selects encoders and decoders by media type. A dynamic resource should:
1. inspect the request `Accept` header;
2. produce a typed result;
3. let the content system choose an encoder;
4. set explicit cache and privacy headers;
5. return `406 Not Acceptable` when no safe representation exists.
## Web control flow
Web extensions can issue redirects and client/server HTTP errors from Script. Use explicit status codes, avoid reflecting raw exception text, and return machine-readable errors for APIs.
## Graphs and documents
Installed modules provide:
* 2D and 3D graphs;
* palettes and fractals;
* Layout2D documents;
* Markdown-to-HTML and Markdown-to-PDF;
* XML and XSL transforms;
* QR codes and image processing;
* semantic formats.
Expensive renderers such as Graphviz, PlantUML, OCR, or PDF may depend on external programs. Check those dependencies during package setup and bound input size and execution time.
## Security
* Treat request variables and uploaded content as untrusted.
* Do not evaluate user-provided Script.
* Encode values through typed renderers.
* Restrict file and network access from public pages.
* Avoid returning .NET objects that expose unintended public properties.
* Set CSP/CORS per resource, not globally for convenience.