API keys
Create a key with the right scopes, connect the plugin, and understand where the key is stored.
The plugin authenticates with a GIMLabs API key. It is inert without one.
Scopes it needs
Keys are created in GIMLabs under Settings > API keys. That needs a Super Admin login, on a Pro or Legacy plan. Tick the access the plugin actually needs:
| Scope | Needed for |
|---|---|
| Projects | Listing and picking a project |
| Locations | The locations layer |
| Map | Boundaries, groups, marker styling and icons |
A key with only Projects and Locations will load boreholes and refuse boundaries and groups, telling you which scope is missing rather than silently drawing nothing.
Tip
A key can also be restricted to named projects. That is worth doing for a key that will live on a field laptop: it limits what the key can reach to the job it is for.
The key is shown once, when it is created. Copy it into your password manager before closing the dialog. Only a hash is stored, so it genuinely cannot be recovered. If you lose it, revoke it and create another.
Connect the plugin
Open Settings
Web > GIMLabs for QGIS > Settings.
Check the base URL
API base URL should be https://api.gimlabs.io/v1 unless you have been
told otherwise.
Warning
The base URL must be https. It decides where the plugin sends your key, and
where QGIS sends the same key every time it polls for updates. The dialog
refuses http rather than quietly correcting it, because silently rewriting
what you typed would hide that you were about to put a credential on the wire
in the clear. http://localhost is allowed, for running the API locally.
Paste the key
Paste it into API key. Keys begin with gim_live_ or gim_test_; anything
else is rejected before it is stored, rather than accepted and failing later
with an unexplained authentication error.
Test connection
Press Test connection. On success it names your company and lists the scopes the key carries, so you can see at a glance whether Map is on the key before you go looking for a boundary that will not load.
The test calls an endpoint that needs no scope at all, which is what lets it tell "this key is not valid" apart from "this key cannot read projects".
The first time you save a key, QGIS asks for its master password. That is QGIS asking, not GIMLabs.
Where the key is stored
In the QGIS authentication database, encrypted behind the QGIS master password, as an entry named "GIMLabs for QGIS API key".
It is deliberately not in your profile settings file, which is plaintext on disk. Only the auth config id goes there, which is a handle rather than a secret. Declining the master password prompt saves nothing: the plugin does not fall back to writing the key in the clear.
The key outlives the plugin
Because the key lives in the QGIS profile rather than the plugin folder, upgrading or reinstalling the plugin keeps it. An update should not log anyone out.
The other side of that: uninstalling the plugin leaves the credential behind. QGIS gives a plugin a chance to tidy up when it is disabled, but no reliable hook before it is deleted, so it cannot clean up after itself.
To remove one:
- Forget stored key in the settings dialog, which also removes the update repository, or
- delete the entry from QGIS's own Settings > Options > Authentication.
Do it before uninstalling if it matters.
Note
Revoking the key in GIMLabs is the thing that actually matters. It takes effect on the next request, on every machine at once, and does not depend on anyone tidying up a laptop.
How much a key is worth
Treat it as semi-public. Its real protection is what it cannot do: it is read-only, it can be restricted to named projects, it is rate-limited, and it can be revoked in one click.
Last updated 2 September 2026