Authenticate an API session
Use an existing Lexoh account with the permissions required by your integration. Protected requests use the session established at sign-in.
POST
/v1/auth/login
Sign in with an existing account
Send username and password as JSON. A successful login returns success, session, user, role and servers. Store the session value securely.
Request Example
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{"username":"USERNAME","password":"PASSWORD"}'Response Example
Selected response fields; user, role and servers are omitted from this example.
{
"success": true,
"session": "SESSION_TOKEN"
}
POST
/v1/device/list
Send the session with each request
Use the SessionID header shown below. Authorization: Bearer SESSION_TOKEN and the session cookie are also accepted. A Bearer value is a session token, not a separately generated API key. The account’s role determines access to each operation.
Request Example
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/device/list" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"page":1,"page_limit":25}'
POST
/v1/auth/mfa
Complete MFA when enabled
If user.mfa_enabled is true, submit the current code with the session before using protected operations. The JSON field is token; code is also accepted. Configured Google or Microsoft sign-in uses /v1/auth/oauth2 to establish a session; it does not change the session headers used by these examples.
Request Example
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/mfa" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"token":"MFA_CODE"}'Response Example
{
"success": true,
"mfa_enabled": true
}
POST
/v1/auth/logout
End the session
Send SessionID when logging out so the server deletes that session. Do not rely only on clearing a client-side token.
Request Example
curl -X POST "https://your-lexoh-server.app.lexoh.com:3000/v1/auth/logout" \
-H "SessionID: SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Response Example
{
"success": true,
"user": null,
"error": null
}Read both HTTP status and the response body
Login returns HTTP 400 for invalid JSON and HTTP 404 when credentials are not accepted. MFA validation errors use HTTP 400. Some protected resource handlers return HTTP 500 with success:false for missing sessions or insufficient permissions; a failed authentication is not consistently represented by HTTP 401.
Response Example
Example from the device list handler, with HTTP 500.
{
"success": false,
"devices": null,
"error": "authentication required."
}Protect sessions and control request volume
- Keep passwords and session tokens out of source control, public pages and logs.
- Use the permissions required for the integration and complete MFA when enabled.
- Use pagination and bounded concurrency. This reference does not specify a fixed per-hour, per-day or concurrent-request quota.