MapitProgramadores Beta mapit.me ↗

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

Scopes

ScopeDá acesso a
mapit:readConta, veículos e subscrição. Obrigatório.
mapit:location:readÚltima localização comunicada e estado do dispositivo.
mapit:routes:readHistórico de trajetos e estatísticas de condução.
offline_accessUm 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