> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-api/panel-api/authentication.md). # Admin Panel authentication 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](/docs/navixy-api/panel-api/getting-started.md). ## 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: * **Secure session duration**: 24-hour 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](/docs/navixy-api/panel-api/resources/account.md). Depending on the deployment method (regional web server or on-premise installation), here are the common endpoint paths: * **European server**: `https://api.eu.navixy.com/v2/panel/account/auth/` * **American server**: `https://api.us.navixy.com/v2/panel/account/auth/` * **Middle East server**: `https://api.me.navixy.com/v2/panel/account/auth/` * **On-premise installations**: `https://api.your-domain.com/v2/panel/account/auth/` ## 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. ```bash 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:** ```json { "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 > 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. ```json {"openapi":"3.1.0","info":{"title":"Navixy Admin Panel API","version":"1.2.0"},"tags":[{"name":"Account","description":"Operations for authenticating a dealer into the Admin Panel, inspecting the permissions granted to the current session, and ending that session. All resources under the /panel/account/ path."}],"servers":[{"url":"https://api.eu.navixy.com/v2","description":"Navixy production server on European platform"},{"url":"https://api.us.navixy.com/v2","description":"Navixy production server on American platform"},{"url":"https://api.me.navixy.com/v2","description":"Navixy production server on Middle East platform"}],"security":[],"paths":{"/panel/account/auth":{"post":{"tags":["Account"],"summary":"Authenticate dealer","description":"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.","operationId":"accountAuth","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["login","password"],"properties":{"login":{"type":"string","description":"The panel login. Numeric in Navixy-hosted installations."},"password":{"type":"string","description":"The panel password.","format":"password"}}}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"`true` if request finished successfully.","readOnly":true},"hash":{"type":"string","description":"The session key. Pass it in the `Authorization` header as `NVX ` on all subsequent requests.","readOnly":true},"permissions":{"$ref":"#/components/schemas/PanelPermissions"}}}}}},"400":{"description":"Bad request. The response body carries the API-level error code in `status.code`. Validation failures also include an `errors` array.","$ref":"#/components/responses/ResponseError"},"403":{"description":"Access denied, error code 11: the dealer is blocked","$ref":"#/components/responses/ResponseError"},"default":{"$ref":"#/components/responses/ResponseError"}}}}},"components":{"schemas":{"PanelPermissions":{"type":"object","description":"Permissions granted to a panel session, grouped by category. Each value lists the actions permitted in that category. Which categories appear depends on the features enabled for the dealer, so a category can be absent rather than empty. Treat an absent category as granting nothing.","readOnly":true,"properties":{"base":{"type":"array","description":"Base panel permissions.","items":{"type":"string"}},"service_settings":{"type":"array","description":"Permissions on service settings.","items":{"type":"string"}},"notification_settings":{"type":"array","description":"Permissions on notification settings.","items":{"type":"string"}},"trackers":{"type":"array","description":"Permissions on trackers.","items":{"type":"string"}},"users":{"type":"array","description":"Permissions on end users.","items":{"type":"string"}},"user_sessions":{"type":"array","description":"Permissions on end user sessions.","items":{"type":"string"}},"tariffs":{"type":"array","description":"Permissions on plans.","items":{"type":"string"}},"transactions":{"type":"array","description":"Permissions on billing transactions.","items":{"type":"string"}},"activation_code":{"type":"array","description":"Permissions on activation codes.","items":{"type":"string"}},"password":{"type":"array","description":"Permissions on the dealer password.","items":{"type":"string"}},"email_gateways":{"type":"array","description":"Permissions on email gateways.","items":{"type":"string"}},"subpaas":{"type":"array","description":"Permissions on sub-dealers. Present only when sub-dealer functionality is enabled for the dealer.","items":{"type":"string"}},"paas_payments":{"type":"array","description":"Permissions on PaaS payments.","items":{"type":"string"}},"paas_tariff":{"type":"array","description":"Permissions on the dealer's own PaaS plan.","items":{"type":"string"}}}}},"responses":{"ResponseError":{"description":"Error response object","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Always false."},"status":{"type":"object","description":"Error status. Present only when an error occurred.","properties":{"code":{"type":"integer","description":"An error code in this API (not a HTTP code)"},"description":{"type":"string","description":"An error description"}}},"errors":{"type":"array","description":"Per-parameter detail, returned with validation failures such as error code 7.","items":{"type":"object","properties":{"parameter":{"type":"string","description":"Name of the parameter that failed validation."},"error":{"type":"string","description":"What was wrong with it."}}}}}}}}}}}} ``` ### 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. ```bash curl -X POST "https://api.your-domain.com/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: ```bash 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: ```bash 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: {% code overflow="wrap" %} ```bash curl "https://api.eu.navixy.com/v2/panel/user/list/?hash=1dc2b813769d846c2c15030884948117&limit=10" ``` {% endcode %} {% hint style="danger" %} **Security Warning**: Query parameter method exposes credentials in URLs, server logs, and browser history. Use only for testing, never in production. {% endhint %} ### 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: {% tabs %} {% tab title="JSON body" %} ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \ -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" \ -H "Content-Type: application/json" \ -d '{"limit": 10}' ``` {% endtab %} {% tab title="Form-encoded body" %} ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \ -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" \ -d 'limit=10' ``` {% endtab %} {% tab title="Query string" %} ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/?limit=10" \ -H "Authorization: NVX 1dc2b813769d846c2c15030884948117" ``` {% endtab %} {% endtabs %} **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 Admin Panel API sessions have a **24-hour lifespan** from creation, regardless of activity. This duration accommodates longer administrative workflows and batch operations. #### Session expiration When your session expires, API calls will return: ```json { "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. When a session expires after 24 hours, you must authenticate again to obtain a new session hash. #### Ending sessions For security purposes, you can explicitly terminate a session before it expires: ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/account/logout" \ -H "Content-Type: application/json" \ -d '{"hash": "1dc2b813769d846c2c15030884948117"}' ``` **Response:** ```json { "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: ```json { "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: ```json { "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: ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/account/get_permissions" \ -H "Content-Type: application/json" \ -d '{"hash": "1dc2b813769d846c2c15030884948117"}' ``` **Response:** ```json { "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** ```bash 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: ```json { "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: ```bash curl -X POST "https://api.eu.navixy.com/v2/panel/user/list/" \ -H "Content-Type: application/json" \ -d '{"hash": "1dc2b813769d846c2c15030884948117"}' ``` > Remember: Your session hash remains valid for 24 hours and can be reused for all admin panel operations during this time. ## 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: ```bash 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 24-hour session lifecycle** in your application architecture 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://navixy.com/docs/navixy-api/panel-api/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.