MapitDevelopers Beta mapit.me ↗

For apps

OAuth

Use OAuth when your app acts for Mapit customers other than you. Each customer signs in on Mapit's own page, sees what your app asks for and decides. Your app never sees their password.

Beta, free for now. OAuth for apps is part of the Mapit API beta: details may change, and there is no uptime promise. See the beta terms.

The basics

Scopes

ScopeGives
mapit:readAccount, vehicles and subscription. Required.
mapit:location:readLast reported location and device status.
mapit:routes:readRoute history and ride statistics.
offline_accessA refresh token, so your app stays connected.

Location and routes are checkboxes on the consent page, and the customer may leave them unticked. Read the scope in the token response to know what you got.

1. Register your app

Dynamic client registration accepts native apps that listen on a loopback address (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"]}'

The port may change between runs; the path must be /callback. For a web app with an HTTPS redirect, ask us to add it: redirects are an allowlist, so nobody can pose as your app.

2. Send the customer to sign in

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 redirects back with code, your state and iss=https://login.mapit.me, or with error=access_denied if the customer cancels.

3. Exchange the code

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

The code works once, for one minute. The answer has access_token (15 minutes), refresh_token and scope.

4. Refresh

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

Each refresh token works once and comes back with a new one. Store the new one before using the access token. Sending a refresh token a second time ends the connection, because it means the token was copied: refresh from one place at a time.

How long a connection lasts