# 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.

<Callout type="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.
</Callout>

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

<Steps>

<Step title="Open Settings">

**Web > GIMLabs for QGIS > Settings**.

</Step>

<Step title="Check the base URL">

**API base URL** should be `https://api.gimlabs.io/v1` unless you have been
told otherwise.

<Callout type="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.
</Callout>

</Step>

<Step title="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.

</Step>

<Step title="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".

</Step>

</Steps>

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.

<Callout type="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.
</Callout>

## 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.