# Claves personales

Una clave personal permite que tu propio código lea tu cuenta de Mapit. Es de solo lectura, salvo que también le dejes gestionar tus conexiones, y es tuya: puedes borrarla cuando quieras.

> **Beta, gratis por ahora.** Las claves personales son parte de la beta de la API de Mapit: pueden cambiar y no tienen garantía de disponibilidad. Consulta las [condiciones de la beta](https://developers.mapit.me/es/terms.md).

## Crea una clave

1. Entra en [login.mapit.me/connections](https://login.mapit.me/connections) e inicia sesión con el email y la contraseña de Mapit.
2. En **Claves personales**, ponle a la clave un nombre que reconozcas, como «Script del garaje».
3. Marca la ubicación, el historial de rutas y la gestión de conexiones solo si tu código los necesita.
4. Vuelve a escribir tu contraseña y crea la clave. Una clave sigue funcionando aunque después cambies la contraseña, por eso Mapit te la pide una vez más.
5. Copia la clave. Empieza por `mapit_` y solo se muestra una vez.

> Trata la clave como una contraseña: que no aparezca en código que compartas ni en capturas de pantalla. Si se filtra, bórrala en la misma página y crea otra.

## Úsala

Envíala como token bearer:

```
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
```

En 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"))
```

## Qué puede hacer una clave

| Permiso | Siempre | Si lo marcas |
| --- | --- | --- |
| Cuenta, vehículos, suscripción | Sí |  |
| Última ubicación recibida y estado del dispositivo |  | Ubicación |
| Historial de rutas y estadísticas de conducción |  | Historial de rutas |
| Ver y desconectar tus aplicaciones conectadas y tus claves |  | Gestionar conexiones |

Una petición fuera de los permisos de la clave responde `403`. Para cambiarlos, crea una clave nueva.

## Consulta sin descargar lo mismo otra vez

Cada respuesta lleva un `ETag`. Devuélvelo en `If-None-Match`; un `304` sin cuerpo significa que nada ha cambiado. Sigue contando para las 30 peticiones por minuto.

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

## Gestionar conexiones

Una clave creada con **Gestionar conexiones** puede ver todas las aplicaciones conectadas a tu cuenta (Home Assistant, Claude, ChatGPT…) y todas las claves, y desconectar cualquiera. Solo las claves personales pueden tener este permiso; ninguna aplicación puede pedirlo. La página de conexiones marca estas claves con «puede gestionar conexiones».

```
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_...
```

> Una clave con este permiso puede desconectar tus aplicaciones. Dásela solo a código de confianza y, si tus conexiones desaparecen sin motivo, borra las claves marcadas con «puede gestionar conexiones». El `name` de una aplicación es el que ella misma se dio, salvo que `builtIn` sea true.

## Límites

En [Límites](https://developers.mapit.me/es/limits.md) están los valores vigentes. Hoy:

- Una clave dura un año. La [página de conexiones](https://login.mapit.me/connections) muestra cuándo caduca cada una.
- Hasta 10 claves por cuenta.
- 30 peticiones por minuto por clave; por encima, la API responde `429` con `Retry-After` en segundos.
