# Personal keys

A personal key lets your own code read your Mapit account. It is read-only, unless you also let it manage your connections, and belongs to you: you can delete it at any time.

> **Beta, free for now.** Personal keys are part of the Mapit API beta: they may change, and there is no uptime promise. See the [beta terms](https://developers.mapit.me/terms.md).

## Create a key

1. Go to [login.mapit.me/connections](https://login.mapit.me/connections) and sign in with your Mapit email and password.
2. Under **Personal keys**, give the key a name you will recognise, such as “Garage script”.
3. Tick location, route history and Manage connections only if your code needs them.
4. Enter your password again and create the key. A key keeps working even if you later change your password, so Mapit asks for it once more.
5. Copy the key. It starts with `mapit_` and is shown only once.

> Treat the key like a password: keep it out of code you share and out of screenshots. If it leaks, delete it on the same page and create another.

## Use it

Send it as a bearer token:

```
export MAPIT_KEY=mapit_...

curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/vehicles
curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status
```

In Python:

```
import os, requests

r = requests.get("https://api.mapit.me/v1/status",
                 headers={"Authorization": f"Bearer {os.environ['MAPIT_KEY']}"},
                 timeout=20)
r.raise_for_status()
for v in r.json()["vehicles"]:
    s = v["state"] or {}
    print(v["vehicleId"], s.get("latitude"), s.get("longitude"), s.get("lastLocationAt"))
```

## What a key can do

| Permission | Always | When ticked |
| --- | --- | --- |
| Account, vehicles, subscription | Yes |  |
| Last reported location and device status |  | Location |
| Route history and ride statistics |  | Route history |
| List and disconnect your connected apps and keys |  | Manage connections |

A request outside the key's permissions answers `403`. To change them, create a new key.

## Poll without downloading the same data

Every answer carries an `ETag`. Send it back in `If-None-Match`; `304` with no body means nothing changed. It still counts towards the 30 requests a minute.

```
# The first answer carries the tag
curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/status

# Send it back: 304 and no body until a vehicle reports something new
curl -sD- -o status.json -H "Authorization: Bearer $MAPIT_KEY" -H 'If-None-Match: W/"..."' https://api.mapit.me/v1/status
```

## Manage connections

A key created with **Manage connections** can list every app connected to your account (Home Assistant, Claude, ChatGPT…) and every key, and disconnect any of them. Only personal keys can have this; no app can ask for it. The connections page marks such keys “can manage connections”.

```
curl -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections
curl -X DELETE -H "Authorization: Bearer $MAPIT_KEY" https://api.mapit.me/v1/me/connections/con_...
```

> A key with this permission can disconnect your apps. Give it only to code you trust, and if connections keep disappearing, delete the keys marked “can manage connections”. An app's `name` is the one it gave itself unless `builtIn` is true.

## Limits

See [Limits](https://developers.mapit.me/limits.md) for the current numbers. Today:

- A key lasts one year. The [connections page](https://login.mapit.me/connections) shows when each one expires.
- Up to 10 keys per account.
- 30 requests a minute per key; over that the API answers `429` with `Retry-After` in seconds.
