# Chaves pessoais

Uma chave pessoal permite que o código próprio consulte a conta Mapit. É só de leitura, a não ser que também seja autorizada a gerir ligações, e pertence ao cliente: pode ser apagada quando se quiser.

> **Beta, gratuita por agora.** As chaves pessoais fazem parte da beta da API da Mapit: podem mudar e não têm garantia de disponibilidade. Ver as [condições da beta](https://developers.mapit.me/pt/terms.md).

## Criar uma chave

1. Abrir [login.mapit.me/connections](https://login.mapit.me/connections) e iniciar sessão com o email e a palavra-passe Mapit.
2. Em **Chaves pessoais**, dar à chave um nome reconhecível, como «Script da garagem».
3. Marcar a localização, o histórico de trajetos e a gestão de ligações só se o código precisar deles.
4. Voltar a introduzir a palavra-passe e criar a chave. Uma chave continua a funcionar mesmo que a palavra-passe seja alterada depois, por isso a Mapit pede-a mais uma vez.
5. Copiar a chave. Começa por `mapit_` e só é mostrada uma vez.

> A chave deve ser tratada como uma palavra-passe: mantê-la fora do código partilhado e das capturas de ecrã. Se for divulgada, apagá-la na mesma página e criar outra.

## Usar a chave

Enviá-la 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
```

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

## O que uma chave pode fazer

| Permissão | Sempre | Se marcada |
| --- | --- | --- |
| Conta, veículos, subscrição | Sim |  |
| Última localização comunicada e estado do dispositivo |  | Localização |
| Histórico de trajetos e estatísticas de condução |  | Histórico de trajetos |
| Ver e desligar as aplicações ligadas e as chaves |  | Gerir ligações |

Um pedido fora das permissões da chave responde `403`. Para as alterar, criar uma chave nova.

## Consultar sem descarregar os mesmos dados

Cada resposta traz um `ETag`. Devolvê-lo em `If-None-Match`; `304` sem corpo significa que nada mudou. Continua a contar para os 30 pedidos 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
```

## Gerir ligações

Uma chave criada com **Gerir ligações** pode ver todas as aplicações ligadas à conta (Home Assistant, Claude, ChatGPT…) e todas as chaves, e desligar qualquer uma. Só as chaves pessoais podem ter esta permissão; nenhuma aplicação a pode pedir. A página de ligações assinala estas chaves com «pode gerir ligações».

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

> Uma chave com esta permissão pode desligar as aplicações. Deve ser entregue apenas a código de confiança e, se as ligações começarem a desaparecer, convém apagar as chaves assinaladas com «pode gerir ligações». O `name` de uma aplicação é o que ela própria escolheu, a não ser que `builtIn` seja true.

## Limites

Os valores atuais estão em [Limites](https://developers.mapit.me/pt/limits.md). Hoje:

- Uma chave dura um ano. A [página de ligações](https://login.mapit.me/connections) mostra quando expira cada uma.
- Até 10 chaves por conta.
- 30 pedidos por minuto por chave; acima disso, a API responde `429` com `Retry-After` em segundos.
