# OAuth

Usa OAuth cuando tu aplicación actúa en nombre de clientes de Mapit que no eres tú. Cada cliente inicia sesión en la página de Mapit, ve qué pide tu aplicación y decide. Tu aplicación nunca ve su contraseña.

> **Beta, gratis por ahora.** OAuth para aplicaciones es parte de la beta de la API de Mapit: los detalles pueden cambiar y no hay garantía de disponibilidad. Consulta las [condiciones de la beta](https://developers.mapit.me/es/terms.md).

## Lo básico

- Flujo de código de autorización de OAuth 2.1 con PKCE (`S256`). Solo clientes públicos: sin secreto de cliente.
- Cada petición de autorización y de token lleva `resource=https://api.mapit.me/v1`. Un token solo vale para el recurso para el que se emitió.
- Dos hosts: la API en `https://api.mapit.me`, y el inicio de sesión y los endpoints de OAuth en `https://login.mapit.me`.
- Descubrimiento: [`https://api.mapit.me/.well-known/oauth-protected-resource/v1`](https://api.mapit.me/.well-known/oauth-protected-resource/v1) indica el servidor de autorización; sus metadatos están en [`https://login.mapit.me/.well-known/oauth-authorization-server`](https://login.mapit.me/.well-known/oauth-authorization-server).

## Scopes

| Scope | Da acceso a |
| --- | --- |
| `mapit:read` | Cuenta, vehículos y suscripción. Obligatorio. |
| `mapit:location:read` | Última ubicación recibida y estado del dispositivo. |
| `mapit:routes:read` | Historial de rutas y estadísticas de conducción. |
| `offline_access` | Un refresh token, para que tu aplicación siga conectada. |

La ubicación y las rutas son casillas en la página de consentimiento, y el cliente puede dejarlas sin marcar. Lee el `scope` de la respuesta del token para saber qué has obtenido.

## 1. Registra tu aplicación

El registro dinámico de clientes acepta aplicaciones nativas que escuchan en una dirección 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"]}'
```

El puerto puede cambiar entre ejecuciones; la ruta tiene que ser `/callback`. Para una aplicación web con una redirección HTTPS, pídenos que la añadamos: las redirecciones son una lista cerrada, así nadie puede hacerse pasar por tu aplicación.

## 2. Envía al cliente a iniciar sesión

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

Mapit redirige de vuelta con `code`, tu `state` e `iss=https://login.mapit.me`, o con `error=access_denied` si el cliente cancela.

## 3. Canjea el 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
```

El código funciona una vez, durante un minuto. La respuesta trae `access_token` (15 minutos), `refresh_token` y `scope`.

## 4. Renueva

```
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 una vez y vuelve con uno nuevo. Guarda el nuevo antes de usar el token de acceso. Enviar un refresh token por segunda vez termina la conexión, porque significa que alguien copió el token: renueva desde un solo sitio a la vez.

## Cuánto dura una conexión

- 30 días desde la última renovación. Una aplicación que renueva la mantiene viva.
- Como mucho un año desde el inicio de sesión; después, el cliente vuelve a iniciar sesión.
- El cliente puede desconectar tu aplicación cuando quiera en [login.mapit.me/connections](https://login.mapit.me/connections). Tu siguiente petición responde `401`.
