Admin Panel authentication

Authenticate to the Navixy Admin Panel API.

The Navixy Admin Panel API provides administrative access to manage the entire Navixy platform, including users, devices, settings, and system-wide configurations. To prevent unauthorized access, Admin Panel authentication uses a simplified but secure session-based model designed specifically for administrative operations.

For the API's base URLs, its resource families, and where the full reference lives, see Navixy Admin Panel API.

Authentication method

The Admin Panel API uses session hash authentication as its sole authentication method. This approach is specifically designed for administrative workflows and provides:

• Long-lived sessions: see Session lifespan

• Administrative privileges: Access to all account and device management functions

• Simple integration: Single authentication step for admin operations

Admin Panel API sessions are completely separate from platform API sessions. You cannot use an admin panel session hash with the platform API, and vice versa.

Base URLs

Admin Panel API authentication is accessible through the /panel/account resource.

The authentication endpoint is the base URL followed by /panel/account/auth/. On the European platform that is https://api.eu.navixy.com/v2/panel/account/auth/, and on a self-hosted (on-premise) installation it is https://api.{your-domain}/v2/panel/account/auth/, where {your-domain} is the domain your installation is served from.

The regional base URLs are shared with the Platform API and are listed once in Base URLs.

Obtaining a session hash

For web usage

To authenticate with ServerMate, send a POST request to the /account/auth/ endpoint with your admin panel credentials: numeric Admin Paned ID and password.

curl -X POST "https://api.eu.navixy.com/v2/panel/account/auth/" \
  -H "Content-Type: application/json" \
  -d '{"login": "your_numeric_panel_ID", "password": "your_admin_password"}'

Successful response:

{
  "success": true,
  "hash": "1dc2b813769d846c2c15030884948117",
  "permissions": {
    "trackers": ["create", "read", "update"],
    "users": ["create", "read", "update", "delete"],
    "accounting": ["generate"]
  }
}

The hash value is your session token - save it securely for subsequent API calls.

The full operation, including every response field and a panel for sending a test request, is below. It is the one Admin Panel operation that requires no existing session, so no Authorization header is sent to it. The hash it returns is then supplied in that header on every other call, which is the canonical method.

Authenticate dealer

post

/panel/account/auth

Authenticate a dealer into the Admin Panel and obtain a session hash. This is the only Admin Panel operation that requires no existing session and no permissions. The returned hash is the credential for every other operation, and the response also reports the full permission set granted to the session, so a client can discover what it is allowed to do without a second call.

Body

loginstringRequired

The panel login. Numeric in Navixy-hosted installations.

Example: 20410

passwordstring · passwordRequired

The panel password.

Example: 12f@14Y$

Responses

200

Session created

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

hashstringRead-onlyOptional

The session key. Pass it in the Authorization header as NVX <hash> on all subsequent requests.

Example: fa7bf873fab9333144e171372a321b06

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array.

application/json

403

Access denied, error code 11: the dealer is blocked

application/json

default

Error response object

application/json

post/panel/account/auth

POST /v2/panel/account/auth HTTP/1.1
Host: api.eu.navixy.com
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "login": "20410",
  "password": "12f@14Y$"
}

{
  "success": true,
  "hash": "fa7bf873fab9333144e171372a321b06",
  "permissions": {
    "base": [
      "get_dealer_info"
    ],
    "service_settings": [
      "read",
      "update"
    ],
    "notification_settings": [
      "read",
      "update"
    ],
    "trackers": [
      "corrupt",
      "create",
      "delete",
      "global",
      "read",
      "report",
      "update"
    ],
    "users": [
      "corrupt",
      "create",
      "read",
      "update"
    ],
    "user_sessions": [
      "create"
    ],
    "tariffs": [
      "create",
      "read",
      "update"
    ],
    "transactions": [
      "create",
      "read"
    ],
    "activation_code": [
      "read",
      "update"
    ],
    "password": [
      "update"
    ],
    "email_gateways": [
      "create",
      "delete",
      "read",
      "send_email",
      "update"
    ],
    "subpaas": [
      "create",
      "delete",
      "read",
      "update"
    ],
    "paas_payments": [
      "create",
      "send_email"
    ],
    "paas_tariff": [
      "read"
    ]
  }
}

For on-premise installations

On-premise installations include default administrator credentials for initial setup:

• Default login: admin

• Default password: admin

Security warning: Change default credentials immediately after installation in production environments.

curl -X POST "https://api.{your-domain}/v2/panel/account/auth/" \
  -H "Content-Type: application/json" \
  -d '{"login": "admin", "password": "admin"}'

Response format is identical to the one in the web usage example.

Using authentication in API requests

Include your session hash in API requests using one of these methods:

1. As request header (recommended)

Include the hash in the Authorization header:

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \
  -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

2. In request body

Include the hash parameter in your JSON request body:

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \
  -H "Content-Type: application/json" \
  -d '{"hash": "1dc2b813769d846c2c15030884948117", "limit": 10}'

3. As query parameter (testing only!)

Append the hash to the URL as a query parameter:

curl "https://api.eu.navixy.com/v2/panel/user/list/?hash=1dc2b813769d846c2c15030884948117&limit=10"

Security Warning: Query parameter method exposes credentials in URLs, server logs, and browser history. Use only for testing, never in production.

The same three options apply to every parameter

The three methods above are not specific to the session hash. Any parameter of any Admin Panel operation can be sent as a JSON body field, as a form-encoded body field, or as a query-string parameter. The examples above show this incidentally: limit travels in the body in the first two and in the query string in the third.

So these three requests are equivalent:

JSON body

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \
  -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" \
  -H "Content-Type: application/json" \
  -d '{"limit": 10}'

Form-encoded body

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \
  -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" \
  -d 'limit=10'

Query string

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/?limit=10" \
  -H "Authorization: NVX 1dc2b813769d846c2c15030884948117"

All three remain supported. The body and query-string forms are genuinely useful for quick testing, and the query-string form in particular is the fastest way to try a call from a browser address bar.

What differs is only how they are documented: the API reference shows the JSON body form, because OpenAPI requires each parameter to be declared in exactly one location and listing all three per parameter is not possible. So treat a request schema in the reference as the canonical form, and apply the equivalence above when you want one of the others. Nothing in the reference should be read as withdrawing them.

The one caveat is the security one already noted: keep the query-string form out of production, because it exposes the hash in URLs, server logs, and browser history.

Two exceptions, both of which the reference states on the operation itself:

• The branding image upload and the user spreadsheet upload require multipart/form-data, and their type and redirect_target parameters must be form parts. Supplying type as a query parameter fails with error code 234.

• panel/timezone/list requires no authentication at all, so none of the three hash methods applies to it.

Session management

Session lifespan

An Admin Panel session expires 30 days after it was issued. The deadline is absolute: it is fixed when the session is created, and using the session does not push it back. An integration calling the API every day still loses the session on day 30.

30 days is a default, not a constant. The period is a per-installation setting, so a self-hosted deployment can use a different one. Handle expiry rather than hard-coding the number.

Session expiration

When your session expires, API calls will return:

{
  "success": false,
  "status": {
    "code": 4,
    "description": "User not found or session ended"
  }
}

To resolve expired sessions, simply obtain a new hash using the /account/auth/ endpoint.

Unlike Platform API sessions, Admin Panel sessions cannot be renewed. There is no panel equivalent of user/session/renew, so when a session expires you must authenticate again to obtain a new hash.

Ending sessions

For security purposes, you can explicitly terminate a session before it expires:

curl -X POST "https://api.eu.navixy.com/v2/panel/account/logout" \
  -H "Content-Type: application/json" \
  -d '{"hash": "1dc2b813769d846c2c15030884948117"}'

Response:

{
  "success": true
}

This immediately invalidates the session hash, making it unusable for further API calls.

This is useful for applications that need to verify capabilities before attempting operations.

Admin Panel permissions

Every Admin Panel API call requires specific permissions. The system compares your account's permissions against the required permissions for each operation.

Permission structure

Permissions are defined as category-operation pairs:

{
  "trackers": ["create", "read", "update"],
  "users": ["create", "read", "update", "delete"],
  "accounting": ["generate"]
}

Available permission categories

• accounting: generate

• activation_code: create, read, update

• base: get_dealer_info

• email_gateways: create, delete, read, send_email, update

• notification_settings: read, update

• password: update

• service_settings: read, update

• sms: create

• subpaas: create, delete, read, update

• tariffs: create, read, update

• trackers: corrupt, create, delete, global, read, report, update

• tracker_bundles: read, update

• transactions: create, read, update

• users: corrupt, create, read, update, delete

• user_sessions: create

Permission denied response

When you lack required permissions:

{
  "success": false,
  "status": {
    "code": 13,
    "description": "Operation not permitted"
  }
}

Checking current permissions

You can verify the permissions of your current session using the get_permissions request:

curl -X POST "https://api.eu.navixy.com/v2/panel/account/get_permissions" \
  -H "Content-Type: application/json" \
  -d '{"hash": "1dc2b813769d846c2c15030884948117"}'

Response:

{
  "success": true,
  "permissions": {
    "base": ["get_dealer_info"],
    "trackers": ["create", "read", "update", "delete"],
    "users": ["create", "read", "update", "delete"],
    "tariffs": ["create", "read", "update"]
  }
}

Error handling

Understanding admin panel authentication errors helps implement proper error handling:

Common authentication errors

• Code 3: Wrong hash - Your API key or session hash is invalid or has been revoked

• Code 4: User or API key not found or session ended - User or session hash don't exist or expired

• Code 7: Invalid parameters - Inserted request parameters are incorrect

Error handling best practices

1. Check the success field before processing response data

2. Implement automatic re-authentication for expired sessions (code 4)

3. Handle account blocking appropriately (code 11) - may require manual intervention

4. Log permission errors for administrative review (code 13)

5. Never use description field programmatically - it may change

Complete authentication example

Here's a step-by-step workflow for Admin Panel authentication on the example of a regional server.

Step 1: Authenticate and get session hash

curl -X POST "https://api.eu.navixy.com/v2/panel/account/auth/" \
  -H "Content-Type: application/json" \
  -d '{"login": "your_numeric_panel_ID", "password": "secure_password"}'

Response example:

{
  "success": true,
  "hash": "1dc2b813769d846c2c15030884948117",
  "permissions": {
    "trackers": ["create", "read", "update"],
    "users": ["create", "read", "update", "delete"],
    "accounting": ["generate"]
  }
}

Copy the hash value (1dc2b813769d846c2c15030884948117 in this example) for use in subsequent requests.

Step 2: Use the hash to authenticate further API calls

Now you can use this hash to authenticate any Admin Panel API request. For example, let's list all user accounts existing under a certain Admin Panel:

curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \
  -H "Content-Type: application/json" \
  -d '{"hash": "1dc2b813769d846c2c15030884948117"}'

Remember: one session hash can be reused for all Admin Panel operations until it expires. See Session lifespan.

Technical service accounts

For secure credential sharing and automated integrations, Navixy supports technical service accounts with limited administrative privileges.

Creating technical accounts

Technical accounts must be created by the Navixy support team:

1. Contact Navixy support with your request

2. Provide the email address for the technical account

3. Receive login credentials from the support team

4. Use these credentials for API authentication

Technical account permissions

Technical accounts have a predefined set of permissions that differ from full administrative accounts:

Permission type	Technical accounts	Full admin accounts
User management	Can add and modify users	Can add, modify, and delete users
Tracker management	Can add, clone, and modify trackers	Can add, clone, modify, and remove trackers
Data plan management	Can change tracker data plans	Can change tracker data plans
Air console access	Can analyze incoming data	Can analyze incoming data and send commands
Plan management	Cannot add, change, or delete plans	Can manage all plans
Platform settings	Cannot modify platform settings	Can modify platform settings

Using technical accounts

Authentication with technical accounts follows the same process:

curl -X POST "https://api.eu.navixy.com/v2/panel/account/auth/" \
  -H "Content-Type: application/json" \
  -d '{"login": "your_numeric_panel_ID", "password": "technical_password"}'

Authentication best practices

Follow these guidelines for secure and effective admin panel authentication:

Security practices

1. Change default credentials immediately on on-premise installations

2. Use HTTPS exclusively for all admin panel API communications

3. Store session hashes securely, never in client-side code or logs

4. Implement session expiration handling in your applications

5. Use technical accounts for automated processes instead of personal credentials

6. Rotate credentials regularly especially for technical accounts

7. Explicitly logout sessions when no longer needed for enhanced security

Integration practices

1. Implement proper error handling for all authentication scenarios

2. Cache session hashes to avoid unnecessary authentication calls

3. Plan for session expiry and re-authentication in your application architecture, without hard-coding the lifetime

4. Test authentication flows in development environments first

5. Document which technical accounts are used by which integrations

6. Support JSON format for all API requests consistently