Replace the Members Portal API key

Self-hosted only: This guide applies to self-hosted deployments. On cloud, the hosted operations team manages licensing — there is no API key for you to change, and the Licensing page is not shown.

The Members Portal API key is the credential the server and the Web Console use to fetch your licence and the agent packages. You replace it on the Licensing page in the Console (see A.1). The Console checks the new key against the Members Portal and stores it encrypted in the database; the web console and the server start using it after they have been restarted.

Before you start

• The new API key from the Members Portal.
• A Console account with settings_enabled, settings_licensing_enabled and settings_licensing_manage (see X.2). Accounts that can manage user permissions receive settings_licensing_manage automatically.
• Shell access to the host running the NetLock RMM containers, for the restart.
• A short maintenance window: both services restart, and the server downloads the agent packages for the new key during its start.

Step 1 — Enter the new key

1. Open Settings → Licensing.
2. In API Configuration, paste the key into New API key.
3. Click Replace API key and confirm.

The Console checks the key against the Members Portal before saving it. A key the Members Portal does not accept — unknown, or belonging to a banned, expired or inactive membership — is not saved, and the page shows the reason. If the Members Portal cannot be reached, the Console asks whether to save the key anyway. Only do so if you are sure the key is correct: with a wrong key the server cannot load its licence after the restart.

After saving, the page shows Restart required together with the last four characters of the new key. Until the restart, the web console and the server keep working with the current key.

Step 2 — Restart both services

In the directory that contains your docker-compose.yml:

cd /home/netlock
sudo docker compose down
sudo docker compose up -d

What happens on start

Both services read the key from the database and write it into their own appsettings.json. Because the key has changed:

• the server discards the licence and the agent packages of the previous key and downloads them again for the new key during the same start;
• the web console discards its cached licence and fetches it again.

You no longer delete license_info.json or internal/packages by hand. The Members Portal has to be reachable during this start; without it the server cannot fetch a licence and stops, as it does with any invalid licence.

Verify it worked

• Settings → Licensing shows the last four characters of the new key under Active API key, and the Restart required notice is gone.
• The licence status, name, and seat count reflect the new licence. If the status looks wrong, use Refresh License Information on that page.

If the Console is not reachable

You can also set the key in the configuration files. Both files are stored encrypted, so you replace their entire content:

1. Stop the services: cd /home/netlock and sudo docker compose down.
2. Replace the entire content of /home/netlock/web_console/appsettings.json and /home/netlock/server/appsettings.json with your plain JSON configuration, with the new key in Members_Portal_Api → ApiKeyOverride.
3. Start the services: sudo docker compose up -d.

On start the files are encrypted again. A key entered into appsettings.json this way takes precedence over the key in the database: it is written to the database, and the licence and packages of the previous key are discarded in the same way as above.

If appsettings.json is mounted read-only, the services cannot write to it, and the key in the file wins on every start. In that setup, change the key in the file rather than on the Licensing page.

Troubleshooting

• A service logs that the stored API key could not be decrypted. The key in the database is protected with Security:Local_Encryption_Key. When this value is set in only one of the two appsettings.json files, that service cannot read the stored key and runs with the key from its own file instead, without changing the database. Set the same value in both files.

Code signing changes trigger an agent reinstall

If the new licence changes the code-signing entitlement — moving from a licence without code signing to one with it, or the reverse — the agents reinstall themselves automatically to match. The server rebuilds its agent packages under the new entitlement during the restart, and managed devices pick up the rebuilt agent on their next sync. No manual reinstall is needed.

Related

• A.1 — System overview & licensing — the Licensing page and what it reports.
• X.2 — Permission reference — settings_licensing_manage.
• Upgrade NetLock RMM — pulling new container images.