Authentication and token management

The authentication model

NextUp uses a session GUID token, not Bearer JWT and not Basic Auth. The model is simple:

Token format

The token is a v4 GUID without dashes, 32 lowercase hexadecimal characters:

55020f7fddda40ceb18636405b161f5a

The Mock Server generates the same format using crypto.randomBytes(16).toString('hex'). The real ERP generates a Windows GUID without dashes.

Client-side validation should check the regular expression ^[a-f0-9]{32}$.

The field in the payload

The token is sent as a top-level property of the JSON-RPC envelope:

{
  "AuthenticationToken": "55020f7fddda40ceb18636405b161f5a",
  "Method": "GetAllArticles",
  "Params": {}
}

Not an HTTP header, but a JSON field

The token is not sent as an Authorization or X-Token header. Always in the JSON body, as a property at the root of the object.

In our Sandbox, the Swagger UI proxy hides this detail. You send the token as an X-NextUp-Token header and the proxy moves it into the envelope when calling upstream.

Multi-company

A token is bound to a single company (the Database parameter). To switch:

Session on company A

{ "Method": "GetAuthenticationToken",
  "Params": { "UserName": "demo_user", "Password": "Demo1234", "Database": "99999999" } }
# -> Token_A

# Operations with Token_A will affect company 99999999

Session on company B

{ "Method": "GetAuthenticationToken",
  "Params": { "UserName": "demo_user", "Password": "Demo1234", "Database": "ALTA_SOC" } }
# -> Token_B (different)

Tokens cannot be reused across companies. A multi-tenant application must keep a (UserName, Database) → Token cache.

Token expiry

Source	Default	Configurable via
Real ERP	depends on the installation (usually hours or days)	NextUp server settings
Mock Server	1 hour (3600s)	TOKEN_TTL_SECONDS in .env

When a token expires, any call returns:

{ "Result": false, "Error": "AuthenticationToken lipseste, este invalid sau a expirat." }

Implementation recommendation:

Explicit logout

A token can be invalidated proactively:

{ "AuthenticationToken": "<token>", "Method": "Logout", "Params": {} }

Useful when:

• A web application has a "Log out" button.
• A batch job has finished and no longer needs the session.
• You want to force re-auth on the next call.

Best practices

1. Cache the token in memory, not on disk. There is no refresh-token mechanism — once expired, perform another GetAuthenticationToken.
2. Do not log the token in clear. Treat it like a password (log only the first 4–8 characters for debugging).
3. Re-auth on a 401-style response, with backoff if it comes from rate-limiting (rare in NextUp).
4. One token per worker. If you run 10 parallel workers, each should obtain its own token — sharing them across processes is fragile.
5. HTTPS in production. The token is not encrypted in transit. Our Sandbox runs on http://localhost for local convenience, but on sandbox.nextup.ro it is served exclusively over TLS.
6. Logout at the end, especially in batch scripts that use dedicated users. It reduces the number of active sessions on the ERP.

Authentication errors

Error	Typical cause	Fix
AuthenticationToken lipseste, este invalid sau a expirat.	Token missing, wrong format or expired	Call GetAuthenticationToken again.
Invalid credentials.	Wrong UserName/Password/Database	Check the combination. The Mock accepts only its predefined combinations.
Campul "Method" este obligatoriu.	Malformed envelope — Method missing	Check the payload; easy to forget when writing JSON by hand.
Payload-ul nu este JSON valid: ...	Malformed JSON	Check commas, double vs. single quotes.

Full catalog: Error catalog.

Advanced technical notes

• CORS: the real ERP does not set CORS headers — calls directly from the browser will be blocked. You must use a server-side proxy. The Swagger UI in the Sandbox is exactly that proxy.
• Parallel sessions: a user can have several active tokens simultaneously (for the same Database). There is no documented server-side limit.
• Hot-reloading settings: password or permission changes in NextUp do not automatically invalidate existing tokens. To force re-auth, stop the web service or wait for natural expiry.