Para aplicações
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.
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 emhttps://login.mapit.me. - Descoberta:
https://api.mapit.me/.well-known/oauth-protected-resource/v1indica o servidor de autorização; os seus metadados estão emhttps://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. O pedido seguinte responde
401.
