ANDROID
How to Connect an Android Phone to Your NetBox Server Safely
Connect Field Companion for NetBox on Android: verify HTTPS reachability, set up a read-only API token, check permissions, and diagnose errors.
You are standing in front of a rack with an Android phone. You know the device exists in NetBox, but you need its record before touching the equipment. A usable mobile connection starts with four checks: the phone can reach your NetBox server, you have an API token, the token’s user can view the relevant objects, and you can open a known device or rack without granting write access.
Field Companion for NetBox is an independent, read-only Android companion for looking up existing NetBox devices, racks and IP addresses, scanning supported equipment labels, and consulting previously retrieved records offline. It connects to the NetBox server you choose; it is not an official NetBox Labs client or a network-discovery tool. The Google Play listing is the installation source. This guide covers the first successful connection, not every possible NetBox deployment or Android build.
Before you start: the four things you need
| You need | How to verify it | Common mistake |
|---|---|---|
| Reachable NetBox HTTPS address | On the phone, verify the intended NetBox hostname is reachable on the authorized network or VPN. Use a correctly trusted certificate. | Assuming a desktop browser’s success proves the phone can connect. |
| API token | Issue a separate, revocable token for the intended NetBox account. Save its full value securely when it is shown. | Using an interactive password or copying only part of a v2 token. |
| View permissions | Check that the token owner can view the required existing Device, Rack, Site and IP Address objects in NetBox. | Believing a token grants access the underlying user lacks. |
| One known test object | Choose a non-sensitive device or rack that the field account is allowed to see. | Treating an empty search as proof that the connection succeeded. |
Step 1. Check the network from the Android phone—not your laptop
Start with the phone on the same authorized access path the technician will use in the field. A NetBox server can live on a private LAN or behind a VPN; the app does not require you to publish NetBox’s administrative interface to the Internet. But Android must be able to reach the server’s API through that network path.
- Identify the NetBox base URL supplied by your administrator, such as
https://netbox.example.org/. The hostname is an illustrative placeholder, not a working service. - Connect the phone to approved Wi-Fi or the organization’s VPN, as applicable. Test DNS resolution and whether the site’s HTTPS certificate is trusted on the phone.
- Make sure a reverse proxy or identity gateway is configured to allow authorized NetBox API requests. A successful SSO login in a browser does not prove a token-authenticated API client can pass the gateway.
- Do not disable TLS verification to make a failure disappear. Ask the server administrator to correct the certificate chain, trusted CA, hostname or proxy configuration.
If your URL opens an HTML sign-in page, a Cloudflare/SSO challenge, or an unrelated website, you have not confirmed usable NetBox API access. The NetBox REST endpoints are rooted under /api/; the official REST API documentation explains endpoint structure and how authentication works. When the app asks for a server URL, start with the deployment’s base address rather than a single endpoint such as /api/dcim/devices/; confirm the installed app’s prompts for unusual subpath deployments.
Step 2. Create a token that can read but cannot write
In your organization’s NetBox web interface, open the user account’s API token management page (navigation labels vary by release and customization). Create a dedicated token for the field device or operator, set an appropriate expiry, and disable write access where supported. Avoid using a global administrator token just because the first search fails.
The underlying NetBox user also needs the correct object-based View permissions. In practice, a technician who needs to identify a rack device may require view access to Devices, Racks and Sites; IP searches additionally require access to the relevant IP Address objects. Constraints can intentionally hide objects from a particular site or region. Ask the NetBox administrator to supply the least set of read permissions needed for the workflow, then test against one object the account is expected to see. NetBox’s object-based permission rules control actual visibility independently of whether a token is valid.
NetBox token v1 and v2 are not interchangeable
As of NetBox 4.5, NetBox supports a newer v2 token format; the current official documentation prefers v2. These values use the form nbt_<key>.<secret> and are normally sent in an HTTP Authorization: Bearer … header. Legacy v1 tokens are sent using an Authorization: Token … header; v1 is deprecated. Those are HTTP protocol formats, not necessarily text you should type into a mobile app’s token input. If the app has a plain API token field, enter the complete token value as requested, without manually adding an HTTP header prefix unless its interface specifically calls for one.
Before using a particular NetBox/server combination in production, verify that the installed Field Companion release accepts its token format. A v2-capable NetBox server does not by itself prove every third-party mobile client implements v2. If the token cannot be retrieved again after creation, replace it with a new revocable token rather than sharing a privileged credential. See the official NetBox token model for versions, expiry, allowed source addresses and revocation.
Step 3. Connect in Field Companion and verify one known record
- Install Field Companion for NetBox from Google Play on a supported Android device. Review the live Play requirements and the product support notes before a larger team rollout.
- Open the app’s connection/setup flow. Supply your organization’s HTTPS NetBox server address and the dedicated API token using the fields shown by your installed version. Do not put the token in the URL.
- Use the app’s available connection or lookup controls to search for a known, permitted device or rack. Verify its name, site and other actually displayed values against the authoritative NetBox web record.
- Try another type of record that your field workflow uses, such as an IP address. If one view works but another fails, investigate per-object permissions instead of creating a broader administrator token immediately.
For a concrete field acceptance check, use synthetic equipment such as a test rack R01 and device edge-sw-01 in a demo NetBox environment. These are example labels, not credentials or live production data. In a real data center, the final acceptance criterion is that the phone shows the correct existing record before an equipment change—not merely that a green connection indicator appears.
Field Companion is read-only. It does not create devices, edit assignments, update cabling, upload site photos, or perform live network scans. If the physical equipment disagrees with NetBox, follow your team’s normal review/change process in the full NetBox interface. The mobile app is a faster reference to recorded data, not an automatic correction mechanism.
Step 4. Prepare for weak connectivity before entering the rack room
The app can retain selected, previously retrieved inventory details for offline viewing. That is not the same as downloading the entire NetBox database or having current server data without a connection. Before entering a low-signal area, open the particular devices and racks you expect to inspect, verify the relevant details while connected, and treat any later offline view as a cached snapshot.
After network access returns, verify important details against the live NetBox source before a high-impact change. For lost-device response or removal, use the app’s storage controls and separately revoke the token in NetBox. The Field Companion privacy policy explains on-device token protection and cache handling. Camera-based label scanning uses Google ML Kit, which may send limited diagnostics/usage signals to Google: do not describe the app as zero-telemetry software.
If it fails, identify the boundary—not just the status code
| What you see | First useful check | Avoid this shortcut |
|---|---|---|
| DNS error, timeout or connection refused | Verify the hostname, phone network/VPN route, firewall and public/private access path. | Do not open the administrator dashboard to the Internet to fix a phone-only route. |
| TLS or certificate trust error | Check the server name, certificate expiry, intermediate chain and installed trust root. | Do not switch off certificate checks or paste secrets into an insecure HTTP endpoint. |
HTML login, SSO page or 404 |
Check base URL, upstream proxy routing and whether an API request is reaching NetBox rather than a browser-only login. | Do not treat an HTML login response as a valid NetBox API result. |
401 or an invalid-token response |
Review exact token format, expiry, revocation, version handling and whether a gateway stripped the header. | Do not assume server version automatically means the app supports the token. |
403 or a missing-credentials response |
Read the response message and identify whether it came from NetBox or a proxy; check permissions and authentication delivery. | Do not assume every 403 is solely a role-permission denial. |
| Connection works; expected record is absent | Confirm the record exists, the correct object type/site was searched, and object-scoped View access covers it. | Do not interpret a filtered result as proof the equipment does not exist. |
| Offline record looks different from live NetBox | Reconnect, consult the live record and follow your team’s discrepancy process. | Do not trust cached data as a real-time change authorization. |
A real NetBox community discussion about Postman and a v2 token shows a user receiving “Invalid v1 token” while expecting v2 authentication. This illustrates why an authorization format mismatch can look like a permissions failure. Another NetBox API discussion documents a request that omitted the required legacy Token header prefix. These reports are context for diagnosis, not evidence that Field Companion has those specific bugs.
Choose the next safe check for your first connection
The following checklist narrows your likely next action based on where the first attempt stops. It is static guidance; it does not contact your NetBox server, test credentials or alter permissions.
Find the next check for your NetBox mobile connection
Applies when: You are connecting an authorized Android field phone to an existing NetBox server with a dedicated API token. No credentials are collected.
Quick answer
First confirm HTTPS reachability from the phone, then a valid API token, then the account's View permissions. Finally, open one known device or rack and verify its identity against NetBox.
What to do
-
Confirm the exact server hostname, certificate trust, DNS and VPN/LAN route on the same phone and network used in the field. A desktop browser test is not sufficient.
-
Use the NetBox account's API token interface. Prefer a supported v2 token on current NetBox, disable writes, apply expiry or source restrictions where appropriate, and do not copy tokens into support logs.
-
A valid token inherits its user's permissions. The account needs access to the specific Device, Rack, Site and/or IP Address objects the workflow actually uses.
-
Look up a permitted non-sensitive test device or rack and compare its identifier and location to the authoritative NetBox page before field deployment.
Where does your first connection stop?
All paths are listed below. Select a symptom to focus on the most relevant path.
Check the phone's DNS and approved network path
Confirm base URL, hostname, firewall rules and that the phone actually joins the required Wi-Fi or VPN. The Android phone must reach the NetBox API; do not expose administrative NetBox routes publicly as a workaround.
Fix certificate trust or API gateway routing
Check certificate hostname, expiry and intermediate chain; a SSO browser challenge is not a NetBox REST API JSON response. Ask your administrator to correct server or gateway settings, not to disable HTTPS verification.
Separate token format, delivery and object permissions
Inspect the sanitized response origin/message. NetBox v2 uses Bearer with the complete nbt_ token at the HTTP layer; v1 uses Token. Verify the app supports your actual token, token validity/expiry, network restrictions, and View rights. Some missing-credential requests return 403.
Check expected object and View permission constraints
Confirm the device/rack exists on the NetBox server, search the correct type/site, and review the user's object View permission filters. A filtered-out record is not proof an asset is absent.
Complete the field acceptance checklist
Verify at least one known device and rack identifier, confirm read-only use and token revocation procedure, and prepare any required viewed records while online. Offline cache is not authoritative fresh inventory.
Did this help?
First-connection acceptance checklist
- Access: the same Android phone and network path that technicians will actually use can reach the intended HTTPS NetBox endpoint.
- Authentication: a dedicated, revocable token is accepted, with version handling confirmed in the installed app; a password or admin-wide shared token was not used.
- Authorization: the field account can view a known existing device and rack, and does not have unnecessary write privileges.
- Correctness: identifiers and site/rack context shown on the phone match the corresponding authoritative NetBox record.
- Offline boundary: the operator understands that previously viewed cached records may be incomplete or outdated.
- Recovery: the team knows how to report a sanitized failure and revoke the token if the phone is lost.
For setup and release requirements, use the Field Companion product page, the Android product directory, and the support page. For authoritative authentication semantics, use NetBox’s current REST API documentation rather than reproducing an old blog post’s header format. ModelGain’s app is an independent third-party field client, not an official NetBox Labs product.