# OAuth

Usar OAuth quando a aplicação age em nome de clientes Mapit que não são o próprio. Cada cliente inicia sessão na página da Mapit, vê o que a aplicação pede e decide. A aplicação nunca vê a palavra-passe deles.

> **Beta, gratuita por agora.** O OAuth para aplicações faz parte da beta da API da Mapit: os detalhes podem mudar e não há garantia de disponibilidade. Veja as [condições da beta](https://developers.mapit.me/pt/terms.md).

## O essencial

- Fluxo de código de autorização OAuth 2.1 com PKCE (`S256`). Só clientes públicos: sem segredo de cliente.
- Cada pedido de autorização e de token leva `resource=https://api.mapit.me/v1`. Um token só é válido para o recurso para o qual foi emitido.
- Dois hosts: a API em `https://api.mapit.me`, e o início de sessão e os endpoints OAuth em `https://login.mapit.me`.
- Descoberta: [`https://api.mapit.me/.well-known/oauth-protected-resource/v1`](https://api.mapit.me/.well-known/oauth-protected-resource/v1) indica o servidor de autorização; os seus metadados estão em [`https://login.mapit.me/.well-known/oauth-authorization-server`](https://login.mapit.me/.well-known/oauth-authorization-server).

## Scopes

| Scope | Dá acesso a |
| --- | --- |
| `mapit:read` | Conta, veículos e subscrição. Obrigatório. |
| `mapit:location:read` | Última localização comunicada e estado do dispositivo. |
| `mapit:routes:read` | Histórico de trajetos e estatísticas de condução. |
| `offline_access` | Um refresh token, para que a aplicação continue ligada. |

A localização e os trajetos são caixas de seleção na página de consentimento, e o cliente pode deixá-las por marcar. Ler o `scope` da resposta do token para saber o que foi obtido.

## 1. Registar a aplicação

O registo dinâmico de clientes aceita aplicações nativas que escutam num endereço de loopback (RFC 8252):

```
curl -X POST https://login.mapit.me/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My app", "redirect_uris": ["http://127.0.0.1:8765/callback"]}'
```

A porta pode mudar entre execuções; o caminho tem de ser `/callback`. Para uma aplicação web com um redirecionamento HTTPS, pedir-nos que o adicionemos: os redirecionamentos estão numa lista fechada, para que ninguém se possa fazer passar pela aplicação.

## 2. Enviar o cliente para iniciar sessão

```
https://login.mapit.me/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=http://127.0.0.1:8765/callback
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256
  &resource=https://api.mapit.me/v1
  &scope=mapit:read mapit:location:read offline_access
  &state=RANDOM
```

A Mapit redireciona de volta com `code`, o `state` enviado e `iss=https://login.mapit.me`, ou com `error=access_denied` se o cliente cancelar.

## 3. Trocar o código

```
curl -X POST https://login.mapit.me/oauth/token \
  -d grant_type=authorization_code -d code=CODE -d client_id=CLIENT_ID \
  -d redirect_uri=http://127.0.0.1:8765/callback -d code_verifier=VERIFIER \
  -d resource=https://api.mapit.me/v1
```

O código funciona uma vez, durante um minuto. A resposta traz `access_token` (15 minutos), `refresh_token` e `scope`.

## 4. Renovar

```
curl -X POST https://login.mapit.me/oauth/token \
  -d grant_type=refresh_token -d refresh_token=REFRESH_TOKEN \
  -d client_id=CLIENT_ID -d resource=https://api.mapit.me/v1
```

Cada refresh token funciona uma vez e volta com um novo. Guardar o novo antes de usar o token de acesso. Enviar um refresh token pela segunda vez termina a ligação, porque significa que o token foi copiado: renovar a partir de um só sítio de cada vez.

## Quanto tempo dura uma ligação

- 30 dias desde a última renovação. Uma aplicação que renova mantém-na ativa.
- No máximo um ano desde o início de sessão; depois, o cliente volta a iniciar sessão.
- O cliente pode desligar a aplicação quando quiser em [login.mapit.me/connections](https://login.mapit.me/connections). O pedido seguinte responde `401`.
