Login flows

All Agent API calls need Referer. Browsers manage this header; the fetch examples use the page origin and strict-origin policy. See required request headers. 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. Start with Sign in with an existing account for a complete HTTP example. For browser or cross-Neuron login, choose a method enabled by your provider.

Client	Start with	Result
First-party back end with Agent credentials	Login	Agent API JWT.
Browser or native app acting for a user	OAuth Authorization Code with PKCE	Scoped OAuth access and optional refresh token.
Terminal, appliance, or input-constrained device	OAuth device authorization	Scoped OAuth access after approval on another device.
Browser already authenticated with Quick Login	Quick login	Agent API JWT for an account on the same Neuron.
Browser opening a different Neuron	Prepare locally, then remote quick login remotely	HTTP session on the remote Neuron; no remote Agent JWT.
Legacy HTTP-auth client	WWW login	Agent API JWT. Prefer another flow for new work.

The direct flow sends the login request, receives jwt and expires, and uses the token as Authorization: Bearer <jwt>. The specification describes Refresh and 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. Quick Login depends on the current HTTP session, so send cookies:

const response = await fetch("/Agent/Account/QuickLogin", {
  method: "POST",
  credentials: "include",
  referrer: window.location.origin + "/",
  referrerPolicy: "strict-origin",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ seconds: 900 })
});

const { jwt, userName, expires } = await response.json();

On the Neuron where the Agent is connected, call PrepareRemoteQuickLogin with its JWT and retain legalId.
In the browser session for the target Neuron, call RemoteQuickLogin with that Legal ID and a user-visible purpose.
The user’s client receives and signs the petition.
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 storage protected by the operating system.
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.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Reports

Token handling

​Direct Agent login

​Documented Quick Login shape

​Documented Remote Quick Login sequence

​Token handling

Direct Agent login

Documented Quick Login shape

Documented Remote Quick Login sequence

Token handling