Para aplicaciones
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.
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 enhttps://login.mapit.me. - Descubrimiento:
https://api.mapit.me/.well-known/oauth-protected-resource/v1indica el servidor de autorización; sus metadatos están enhttps://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. Tu siguiente petición responde
401.
